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Preface 



This book had its origins in the programme of external short courses on microcomputers offered by 
the Department of Electronic and Electrical Engineering at the University of Salford. Several 
hundred people attend our courses each year, and the material presented here has been continuously 
honed and refined in the light of their comments and suggestions. 

The contents of this book apply in general to all CBM microcomputers, although some sections 
are specific to 2000, 3000 and 4000 series PET's. 

We suggest that, no matter what your own particular field of interest, you should read chapters 6 
and 12, on programming style and interactive programming. If you are involved in business, administ- 
ration, or other data handling applications you will probably find chapters 1 1 and 8 on disk data 
storage and the use of the CBM printer particularly relevant, while if you are a hobbyist, or involved in 
education, the sections on graphics and string handling may be of most interest. 

We hope that you will find as much enjoyment and instruction in reading this book as we have 
found in writing it, and that you will continue to enjoy the fun and satisfaction of computing in the 
even more exciting years which lie ahead. 

Finally, if the task of typing in these programs is just too overwhelming , a disk containing each of 
them is available. Please see the final page in this book. 

E A Flinn 

A E Hill 

R D Tomlinson 
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1 



Introduction to the 
PET/CBM Family 



The popular PET/CBM microcomputer was first introduced in 1978 and was one of the first desktop 
computers to incorporate a built-in monitor screen. Although the original concept remains largely 
unchanged there have been several significant changes to the operating system, the latest of which 
incorporates an upgraded BASIC called BASIC 4. BASIC 4 has given the PET faster string 
processing facilities and a set of disk operating commands which considerably simplify the use of the 
disk drive unit. 

The earliest version of the PET had a small calculator-type keyboard and a built-in cassette unit. 
The very early machines operated with BASIC 1 and contained what are known as "Old ROMs". ( A 
ROM is a Read Only Memory chip). These were quickly superseded by an improved BASIC 
operating system called BASIC 2. It was possible to upgrade the old BASIC 1 machines to BASIC 2 
by installing a set of "new ROMs" . BASIC 2 included a disk drive control system and a machine-code 
monitor, features which were not available in BASIC 1. The early machines were called the 2001 
series (new ROMs were fitted to late models) and could be purchased with different amounts of 
user-accessible memory; 4K, 8K, 16K and 32K versions were produced. A large keyboard was 
introduced, initially for the 16K and 32K versions of the 2001 models; this feature has since become a 
standard fitting and the small keyboard models have been discontinued. Large keyboard machines 
require a separate cassette tape unit. 

The 3000 series of PETs was introduced next, operating with BASIC 2, and the 4K version was 
discontinued. In late 1980 the 4000 series, operating with BASIC 4, was introduced. The first 4000 
machines retained the 9" monitor screens and were essentially 3000 models equipped with BASIC 4 
ROMs. Current 4000 series PETs have larger (12") monitor screens and incorporate some additional 
features, such as automatic repeat on the cursor control keys. All machines mentioned so far have a 40 
column screen, which is a disadvantage for commercial users, particularly when word processing 
applications demand an 80 character per line printout. 

The 8000 series, operating with BASIC 4, represents a recent extension to the PET/CBM range: 
an 80 column screen together with a 96K memory is now available and an improved disk drive (8050) 
system enables the machine to operate quite sophisticated business-orientated software packages. 
CBM have also in recent years introduced a low priced home computer range of machines called the 
VIC series which are designed to operate with a domestic TV receiver. 
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2 



Cursor Controlled Graphics and 
Animation 



The PET graphics facilities are built-in features of the keyboard and consist of 64 characters which are 
generated with the shift key, for the "standard" character set. This is a low resolution graphics facility 
but the wide range of available characters gives the PET quite a comprehensive sketching capability. 

Close inspection of the screen reveals that each character is generated in an 8 x 8 matrix of 
points. Each point is called a pixel. If high resolution is required, additional hardware can be installed 
which allows the operator to program the control of any individual pixel or combination of pixels. (See 
Appendix C on extension ROM packages.) 

Normally the screen can display a total of 1000 characters; 25 lines and 40 columns are available 
for text and graphics displays. Several different techniques are available for sketching and achieving 
animation effects. The cursor controls can be programmed into strings, while the POKE and PEEK 
commands can be used to place characters into specific screen positions and to identify the contents of 
any screen location. 

2. 1 SKETCHING WITH THE PRINT COMMAND 

The simplest programmed sketching technique uses only the PRINT instruction to place strings of 
characters in specific screen locations. The following program is an example of this technique. The 
sketch can be produced directly and the program line number and PRINT statements can be inserted 
later, using the cursor controls and the editing facilities to avoid overwriting details of the sketch. 



Exam 


pie 2.1 




18© 


PRINT "3" 




1 1 8 


PRINT 




120 


PRINT 




1 38 


PRINT- 




140 


PRINT 




158 


PRINT- 




1 68 


PRINT" 


Illifll^iiilliiiiiWii! 


1 79 


PRINT" 


1 1 " 


188 


PRINT" 


!i BEWARE OF jg; " 


1 98 


PRINT" 


$! i; 


288 


PRINT" 


!i THE BULL § " 


388 


PRINT" 


$1 ill " 


318 


PRINT" 


ISiiiiii^Wiliiii^iili^il " 



Scrolling will occur if the number of lines exceeds 25, and the automatic READY can cause the 
screen to scroll if a sufficient lower margin has not been allocated. The PRINT instruction is used in 
lines 1 10 to 150 in order to start the sketch five lines down screen. Quotation marks must be used to 
define the strings of characters which will probably contain blanks (produced by the space key). The 
second quotation mark may be omitted at the end of a program line; however, this practice should be 
handled with care, particularly when concatenation is employed. (That is, when strings are joined end 
to end.) 

19 
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2.2 PROGRAMMED CURSOR CONTROL 

The provision of cursor controls is a powerful and unique feature of Commodore BASIC. The cursor 
controls can be used in the direct mode and no doubt the reader is already familiar with this mode of 
operation. When programmed into a string, each control is represented by a special symbol which is 
printed in a program listing as shown in the following table. 

Table 2.1 

CURSOR CONTROL SYMBOLS 



£8 CURSOR HOME 

3 CLEAR SCREEN 

gl CURSOR DOWN 

3 CURSOR UP 

fej CURSOR RIGHT 

II CURSOR LEFT 

J3 REVERSE CONTRAST ON 

■ REVERSE CONTRAST OFF 

Cursor controls can be programmed into a string with the aid of the quotation marks key. This 
key acts like a switch, enabling the cursor movement to be programmed into a string. A second typed 
set of quotes, or the RETURN key, switches the PET back into direct cursor mode. The INSerT key 
also switches the PET into programmed cursor mode, thus allowing cursor controls to be edited into a 
string. After the inserted space or spaces have been filled the PET automatically returns to direct 
mode. 

When the INST key has been used to insert extra spaces into a string the DELete key is also 
switched into programmed mode (indicated by a reverse contrast T), and the delete function cannot 
be operated until all inserted spaces have been filled. This means that it is not possible to erase directly 
an edited character if inserted spaces remain in the string, - a source of confusion for the beginner. 

The following set of examples is intended to show how the programmed cursor controls can be 
used to produce graphics and text displays on screen. 

Example 2.2 

18 PR I NT "3" 

20 PR I NT " WWUMFETBlBFETMMaPETgrPETjyET " 

This program produces five "PETs" arranged in V formation with the third "PET" printed in 
reverse contrast. The cursor control character printed in line 10 clears the screen, and on line 20 seven 
"cursor right" controls are included before the first PET is printed. Line 30 merely shifts the cursor 
down screen so that the automatic READY does not mask the display. 
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The cursor automatically shifts to the right after printing a character on screen. This feature can 
be a source of confusion when generating graphics with the cursor controls, and the next program 
illustrates the point by printing out the "PETs" in a vertical line. 

Example 2.3 

18 PR I NT "3" 

26 PR I NT " PETSBMMPETBaUFET " 



Three "left cursor" controls are necessary to allow for the automatic cursor advance. 

The semicolon is used to concatenate strings and is a very important graphics control character. 
Strings of cursor controls can be concatenated in exactly the same way as strings of characters and the 
next program demonstrates this process. 

Example 2.4 

1 PR I NT •■ jiwwiwimww 1 .? 

20 FOR I = lTO20sPRINT"i$"; :NEXT I 

30 FOR I = 1 T06 : PR I NT " mm" ," : NEXT I 

40 FOR I = lTO20:PRINT"lilI" ; sNEXT I 

50 FOR 1 = 1 T06 s PRINT "HI!" .; : NEXT I 

60 PR I NT " aSKIUUUUNO PARK I NO " ; 

70 PR I NT " iMSlHiUlB" ; 

SO FOR I = 1 T08 : PR I NT " »H" .; : NEXT I 



This program produces a signpost sketch similar to example 2.1 . However, instead of using direct 
PRINT statements to produce the sketch, a series of concatenated strings are combined using FOR . . . 
NEXT loops. This is not meant to be the simplest way of producing the end result, which in this case 
would be the method used in 2. 1 The program serves merely as an illustration of a technique which can 
be developed further to give increasing programmed control of a display or animation. The semico- 
lons are included to concatenate the sequential printing of the character as the FOR . . NEXT loops 
are executed. Line 30 produces a vertical line, 6 characters long; the string contains a "cursor down" 
control followed by a "cursor left" control followed by the character. The controls move the cursor 
into a screen position immediately below the last printed character, so that a vertical line is created as 
the loop is executed. The automatic cursor advance only occurs when a character is printed and is not 
associated with the cursor positioning controls. 

The SPC command may be used to replace some of the programmed cursor movements used in 
the last program. The argument of the SPC must be a positive number in the range to 255 and the 
command moves the cursor through the specified number of spaces, to the right. The command is 
quite versatile because a variable or an expression containing variables may be used for the argument 
provided that numeric values in the allowed range are generated. 

Lines 10 and 70 of the last example can thus be modified to:- 



10 PR I NT" 3" SPC < 20' 
70 PRINT SPC<115> 



i' .' 
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SPC does not require quotation marks and can be used more than once in a program line. 
For example 

Example 2.5 

1 8 PR I NT " 3" SPC •:: 258 > SPC ■:: 245 > " M I DOLE " 

The cursor move is started from the position directly before SPC is encountered; this command 
provides automatic concatenation. 

2.3 ANIMATION USING PROGRAMMED CURSOR CONTROLS 

Any character or group of characters can be printed in sequence with the aid of a FOR . . . NEXT loop 
to produce interesting animation effects. The cursor controls, together with the characters and an 
appropriate number of blanks (produced by the space key) are written as a string. Each pass through 
the loop causes the characters to be printed; the string is organised so that blanks are printed to erase 
the characters printed during the previous pass. 

Example 2.6 

180 PR I NT "3" 

lie FOR J=l TO 39 

129 PRINT" XH"; 

136 FOR T=l TO 50: NEXT T 

140 NEXT J 

This program moves a single character (the X symbol) from left to right on the top line of the 
screen through 39 successive print positions. The blank is positioned before the character so that after 
the first print the previous character can be erased. Each printed string contains two characters (the 
blank is a character) and so the last PRINT positions the X at the end of the line 40 spaces from 
HOME. The semicolon concatenates the sequential printing and the "cursor left" control positions 
the cursor over the character so that it can be erased by the blank during the following pass through the 
loop. 

The maximum speed of the animation is determined by the string processing speed of the PET 
and if slower movement is required then a longer time delay loop can be incorporated. 

The 4000 series of computers has a faster string processing facility than earlier machines. This 
improvement produces a speed increase of approximately 5 times. Hence the time delay loop 
becomes essential if you are working with a 4000 series PET. 

The next program combines the previous program with a concatenated movement from right to 
left. 
Example 2.7. 

18 PR I NT "3" 

20 FOR J=l TO 39 

30 PRINT" XII"; 

35 FOR T=l TO 58: NEXT T 

48 NEXT J 

50 FOR J=l TO 39 

60 PRINT" 111X11"; 

65 FOR T=l TO 58: NEXT T 

78 NEXT J 

88 G0T028 
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Line 60 in the previous listing produces the right to left animation. The string starts with the blank 
which erases the last character printed by the first movement. This is followed by two "cursor left" 
controls so that the X is printed in an adjacent position to the left of the blank. The last character in the 
string is a "cursor left"; this is included so that the cursor is positioned over the character, ready to 
erase it during the next pass. Vertical movement may be achieved using similar techniques: 

Example 2.8 

18 PRINT :H»»»»»»W»»I ; 

26 FOR J=l TO 24 

30 PRINT" SHXH"; 

46 NEXT J 

56 FOR J=l TO 24 

60 PRINT" ZHKH"; 

70 NEXT J 

89 GOTO 10 

The start position of the movement is set by the "cursor left" controls, incorporated in the string 
at line 10. In line 30 in the last program the string contains the cursor controls which are necessary to 
place the X in position below the blank. Finally the "cursor left" control positions the cursor over the 
character, ready for the next pass. 

In order to follow the movement of the cursor in these examples, it is sometimes useful to plot the 
moves on squared graph paper. In the next program, a diagonal movement of two characters is 
achieved by combining in the string (line 30) the necessary character grouping and erase procedures. 
The movement is slowed down by the addition of a time delay loop at line 40 and if only one X is 
desired the string may be terminated after the 4th character ("cursor left"). 
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mple 2.9 


18 


PR I NT "3" 


20 


FOR J=l TO 28 


38 


PRINT" SKIIII BTC3"; 


48 


FOR 7=1 TO 58: NEXT T 


58 


NEXT J 


68 


GOTO 10 



The next program incorporates most of the graphics techniques described in this chapter. 
Example 2.10 

1 88 PR I NT " U" SPC < 200 > 

110 PR I NT " S ft L F O R D " 

120 FOR Jal TO 28 

130 FOR T=l TO 58 .-NEXT T 

140 PRINT"BdPETBflHIB »HIBj&r~aMUIB BN3XH1I" ; 
150 FOR 7=1 TO 50 :NEXT T 

168 PRINT"BjaPETHBliiiP tniBjBBNniHHB^BI ZXXHW" ; 

178 NEXT ,T 

188 PRINT"HSBfflSM" 

1 98 PR I NT " 3" SPC < 1 5 > " COURSE " 

288 FOR T=l TO 180:NEXT T 
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2 1 8 PR I NT " 3" SPC < 1 5 > " jaCOURSEi" 
228 FOR T=l TO 186 s NEXT T 
230 GETfl*:IFR*=" "THEN258 
248 GOTO 198 
250 END 

Lines 140 and 160 produce an animated figure (a man) which proceeds to "walk" across the 
screen from left to right. The string in line 140 generates the figure and is designed so that the blanks 
erase the trailing edge as left to right movement is achieved. In order to assist with the interpretation 
of this string a letter B has been inserted into the blank positions. Without this device it becomes 
difficult to distinguish some of the graphics characters which have been used to build up the figure. 
The method which has been used in this example to create the animation can be summarised as 
follows:- 

1 The "man" is composed of four rows of characters. 

2 The string (line 1 40) generates the top row first and then proceeds to build up rows 2, 3 and 4 m 
sequence. 

3 Each row starts with a blank and after positioning the characters the cursor is moved to the start 
(left hand edge) of the next row. 

4 After the figure is completed the cursor is moved back to the top row and positioned over the first 
character so that the next pass through the loop will erase the trailing edge. Line 160 is very similar 
to line 140; close inspection reveals that the only changes are associated with the graphics 
characters used to form the arms and legs. These are changed so that a "walking figure" can be 
simulated. 

The GETA$ in line 230 provides an exit from the program by pressing the space key, and the next 
program can be added if more practice in animation techniques is required. 

Example 2.11 

258 PRIHT"is!SMfiBM3S".! 
268 FOR J=l TO 18 

270 print" milium s ja lamii sPEimaaaum n ,-:roti".; 

288 PRINT" £lHIIilll % J3 SHIM fiFETSaiiMI - y ^HT ; 

2.90 NEXT J 

380 PRINT"HSH" 

3 1 PR I NTSPC -:: 1 5 > " U'-JS "•_HiaPEHTS" 

328 FOR T=l TO 28: NEXT T 

338 PR I NTSPC < 1 5 > " H.J3 ■»_Hia & E STT ■" 

348 FOR T=l TO 28: NEXT T 

350 GOTO310 

368 END 
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PEEK and POKE 
Graphics 



CHARACTER CODES 

The keyboard characters are recognised and stored in computer memory using two codes, the PET 
ASCII code and the PEEK/POKE code. Each of the codes may be used in BASIC programs with the 
aid of the following guide lines. 

3.1 THE PET ASCII CODE 

This code is a development of the ASCII (American Standard Code for Information Interchange) 
Code which is widely used in computer systems to specify characters and keyboard function operators. 
The code has been extended by CBM to include the characters and controls which are unique to the 
PET keyboard. Each character and control key is assigned a decimal number in the range to 255, 
except for the reverse contrast characters which have no ASCII representation. Figure 3.1 shows the 
code numbers related to the large PET keyboard. PETs with small keyboards use the same ASCII 
character code but the keys are arranged in different locations. 

The BASIC functions ASC and CHR$ use this code for character representation. 

e.g. ?ASC("A") returns the number 65 

and ?CHR$(65) returns the letter A. 

CHR$ translates the decimal ASCII code number into the equivalent character and can be used 
to specify characters which cannot normally be used in strings. 

e.g. ?CHR$(34); "PET"; CHR$(34) 

returns the word "PET" in quotation marks on screen. 

The ASCII code number for the quotation mark is 34; without the use of the CHR$ function it is 
not possible to program this symbol into screen text. It is also possible to program the cursor controls 
and the RETURN key with the aid of CHR$ and this function is used extensively when formatting text 
for the printer. 

The ASC function finds useful graphics applications, some of which are illustrated later in this 
chapter. 

3.2 THE PEEK/POKE CODE 

This code is used in conjunction with the PEEK and POKE functions in order to POKE a character 
into screen memory or to PEEK a specific screen memory location in order to establish the contents. 
Each keyboard character is again assigned a decimal number in the range to 255 but since in many 
cases the PET ASCII numbers are not the same as the PEEK/POKE code numbers, the use of the two 
codes requires careful management. Figure 3.2 relates the PEEK/POKE code to the large keyboard. 

When using the PEEK and POKE functions to generate characters on screen it is necessary to 
know the screen locations in PET memory. The contents of the screen are stored in a block of 1000 
memory locations, ranging from 32768 (top left) to 33767 (bottom right). These rather cumbersome 
numbers must be used as the argument in the PEEK/POKE functions. 
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POKE 33767,1 

when used as a direct mode command will produce a letter A in the right hand bottom corner of 
the screen. 

If this is followed by ?PEEK(33767) the number 1 is returned. 

Any other screen location can be similarly addressed using other PEEK/POKE character code 
numbers to generate specific characters. 

If the Alternate Character Set is used (POKE 59468,14) the codes now represent the new set of 
characters. 
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Code numbers reflect the new key interpretations 

e.g. ?ASC("a") returns 65 

and ?CHR$(65) returns "a" 

Similarly, POKE33767, 1 now produces an a in the right hand corner of the screen and the 
command ? PEEK(33767) will return the number 1. 

3.3 PEEK/POKE CODE CHARACTER RELATIONSHIPS 

There are some useful relationships within the PEEK/POKE code which help the user to avoid 
constant reference to the tables. 

The addition of 128 to any "normal contrast character" code number will produce the reverse 
contrast code number. 

e.g. POKE33767, 1 + 128 

returns a reverse contrast "A" 

and if this is followed by 7PEEK33767 then 129 is returned. 

Shifted characters are related in PEEK/POKE code to unshifted characters; the addition of 64 to 
the code number for any unshifted character produces the shifted version. 

e.g. POKE33767, 22+64 

returns a shifted V - the symbol X. 
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3.4 RELATIONSHIP BETWEEN THE PET ASCII AND THE PEEK/POKE CODES 

It is possible to use the ASC function as the second argument in the POKE function and thus avoid 
reference to the code look-up table. Unfortunately, the relationship between the two codes is not the 
same for all keys so if the following procedure is used a little practice will be required. 

The keyboard is divided into two blocks of keys; 

Block 1 includes all the alphabet keys and several of the graphics keys, i.e. @ , \ ,<-,[,] , and t . 
All other characters form Block 2. 

Block 1 relationships 

The PEEK/POKE code number may be obtained by subtracting 64 from the ASCII code number. 

e.g. POKE Z, ASC("N")- 64 

generates the letter N at screen location Z. The code relationships for reverse contrast and shifted 
characters can also be incorporated into the POKE argument. 

e.g. POKE Z,ASC("V")-64+64 

or simply POKE Z,ASC("V") 

returns the graphics symbol "X" 

and POKE Z,ASC("N")-64+128 

returns a reverse contrast N at screen position Z. 

Block 2 relationships 

For unshifted characters the ASCII and the PEEK/POKE code numbers are identical. 

e.g. POKE Z,ASC("$") 

generates the $ symbol and 

POKE Z,ASC("5") 
generates a 5 at screen position Z. 

The rules for obtaining shifted and reverse contrast characters are unchanged, i.e. 

POKE Z,ASC("5") + 128 

produces a reverse contrast 5. 



3.5 GENERATING GRAPHICS WITH PEEK/POKE 

The following programs in this chapter are examples of the use of the PEEK/POKE code functions for 
generating graphics displays. 

The screen is organised into 40 columns and 25 rows, so that any location can be addressed using 
the formula 

32768+40* (row number) + (column number) 
0-24 0-39 

The POKE command can be used with variables in both the arguments and the following exercise 
illustrates this facility, printing on screen a set of 38 characters (numbers 1 to 38 in the PEEK-POKE 
code). The shifted and reverse contrast characters are also generated in tabular form. 
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Example 3.1 

108 REM POKE CODE RELATIONSHIPS 

lie PRINT "3" : C=0 

126 X=32808 

130 FOR V=l TO 19 

140 C=C+1 

150 POKEX+V+C-V 

1 60 POKEX+ V+C+8Q , V+64 

1 70 POKEX+V+C+ 1 60 , V+64*2 

1 80 POKEX+V+C+240 ., V+64*3 

190 IFV=38THEN258 

200 NEXT V- 

210 print" laneBHPOTKBmi 

220 X=328 10+40* 10 
230 FOR V=20 TO 38 
240 GOTO 140 

250 PRiNT'^iinafleumPBHiHaaa" 

260 PR I NT "FIRST ROW-PET POKE CODE NUMBERS 1 TOSS 
270 PRINT"SSECOND ROW+64, THIRD +1 28 , FOURTH +192. 
280 GETfl*:IFR*=""THEN 280 
290 END 

In line 150 the screen address is determined by the sum of the three parameters X, Y and C. A 
value of 32808 (2 lines down screen) has been chosen for X; this serves as a reference point for all 
subsequent screen positions. The FOR . . . NEXT loop serves to increment Y through the values 1 to 
19 and C is also incremented so that two spaces are incorporated between the individual elements in 
the table. Y is also used to establish the PEEK/POKE code number for the second part of the POKE 
argument. Lines 1 50 to 1 80 generate four rows of characters. The second row, generated at line 1 60 is 
spaced two rows down screen from the first. This is accomplished by the addition of 80 to the POKE 
screen address; also the addition of 64 to the PEEK/POKE code number ensures that the set of shifted 
characters is produced. Sets of reverse contrast characters are generated at lines 170 and 180. The 
rows are labelled 1, 2, 3, 4 with the aid of the programmed cursor controls on lines 210 and 250. This 
process is repeated for Y values 20 to 38 in order to produce a second block of characters (with code 
numbers 20 to 38). The GET loop at line 280 serves only to suppress the READY at the end of the 
program but could be used to direct the program to a further set of characters if required. 

The next program further illustrates the potential of the POKE command, generating a set of 
four rectangular borders on screen. The X variable is used sequentially to reduce the dimensions of 
the border and the GET at line 250 stops the execution of the program until an input from the 
keyboard is detected. Further features may be added to the end of this example. The GET holding 
loop provides the user with a convenient keyboard-controlled switch. 

Example 3.2 

108 PR INT "3" :X=0 

110 FOR K=1T039-2*X 

1 20 P0KE32767+40*X+X+K ., flSC < " & " > +64 

130 NEXT K 

140 FOR K=0TO23~2*X 

1 50 POKE32807+40*X -X+40*K ., FlSC < " & " > +64 

160 NEXT K 
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170 FOR K=1T039~2*X 

1 89 POKE33768-40*X-X-K ., flSC < " & " > +64 

190 NEXT K 

200 FOR K=0TO23-2*H 

210 PQKE33728~48*X+X--40*K , ASC < " & " > +64 

220 NEXT K 

230 IFX=8 THEN250 

240 X=X+2 : GOTO 110 

250 GET A$ : I F A*= " " THEN250 

The PEEK command can be used to scan the screen for character location information which can 
then be used to control the display. This function is demonstrated in the next program which reverses 
in sequence the contrast of all characters except the blank (POKE code number 32). The speed with 
which the PEEK and POKE functions operate within a BASIC program is limited and can only be 
increased by using machine code routines (see chapter 14). 

Example 3.3 

100 FOR X=32768 TO 33767 

110 r=peeko<:> 

120 if peek <!x>>= 128 then a=a-256 

130 if peek 0-0=32 then 170 

1 40 POKEX , A+ 1 28 

150 GETA*:IF A*<>" "THEN 170 

160 GETA$:IF R*<>" "THEN 160 

170 NEXT 

180 GOTO 100 

Each screen location is PEEKed in turn and the PEEK/POKE code number assigned to the 
variable A at line 110. The reverse contrast character is POKEd back into the same location at line 
140. Line 120 is required so that any character which is already in reverse contrast is generated with 
normal contrast. All reverse contrast characters have POKE code numbers > = 128 so if this is the 
case then A=A-256 produces normal contrast; code numbers greater than 255 are not allowed and 
without this device the program would crash at line 140 when the PEEK function identified a code 
number >= 128. 

Lines 150 to 170 can be omitted but provide an interesting example of the use of the GET 
command. The space key is used to stop and start the execution of the program. 

The POKE function can also be used to control (from the keyboard) the movement of a character 
or group of characters - a feature of many computer games. 

Example 3.4 

100 REM CONTROLLED MOVE - GRAPHICS DEMO 

110 REM 

120 REM 

130 REM THE NINE DATA PAIRS SET UP THE 

140 REM DIRECTION OF THE MOVE. 

150 REM 

160 REM 2-DOWN, S-UP, 6-RIGHT ETC 

170 REM 

ISO REM N IS THE INPUT AND P. IS THE 
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198 REM DIRECTION VARIABLE. 

208 REM 

210 FOR 1=1 TO 9 

220 READ H*<I>,R<I> 

230 DATA7, -41, 8, -48, 9, -39, 6, 1,3, 41, 2, 40, 1,39, 4, -1,5,0 

240 NEXT 

250 L=33267 

260 K=0 

270 PR I NT "3" 

280 L=L+K 

290 POKE L,65 

300 GET X* 

310 FOR 1=1 TO 9 

320 IFX*=N*CI> THEN 350 

330 NEXT 

340 GOTO 260 

350 K=R<I> 

360 GOTO 270 

In the preceding program two arrays N(I) and R(I) are filled with data which links the movement 
of a specified character with keys 1 to 9 on the keyboard. The associated elements in the two arrays 
produce movement in the desired direction, e.g. N(2) contains 8 and R(2) contains -40, so that when 
an 8 is keyed in and detected by the GET at line 300, K is given the value -40. This value is then added 
to the screen address at line 280 and the character is regenerated one position up screen. Line 250 
establishes an arbitrary start position and in line 290 the POKE code number 65 is an arbitrary 
character specification. 

As a final example of the use of PET graphics facilities the framework of a simple shooting alley 
game is constructed. Most of the features which have been described in the previous two chapters are 
incorporated and it is left to the reader to produce his own variations. 

Example 3.5 

100 H=0 

110 PR I NT "3 

12© F0RI=1T038 

1 30 P0KE32763+ I , ASC < " & " > +64 : NEXT 

140 PR I NT" g| 

150 F0RI=1T023 

160 PR I NT "B"; zNEXT 

170 F0RI=1T038 

180 PRINT" •||"; 

190 GETA$ 

20© IFA*="E"THEN250 

2 1 FOR J= 1 T020 : NEXT J 

220 NEXT 

230 PRINT" "; 

240 GOTO 14© 

250 PR I NT "3"; 

260 N=N+1 

270 F0RI=1T023 

280 PRINT" 311*11"; : NEXT 
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299 FORH=32769TO32807 

380 T=PEEK<H> 

310 IFT=102THEN390 

320 NEXTH 

330 PR I NT "3 

340 PRINT"VOU FIRED" ;N; "SHOTS" 

350 PRINT" IF VOLI WISH TO PLfiV HGHIN TVPE V" 

360 GETfl* : I FR*== " V " THEN 1 00 

370 I FR$= " " THEN360 

380 END 

390 GOTO 140 

400 END 
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Manipulating Text - 
String Handling 



INTRODUCTION 

A string is composed of a sequence of alpha-numeric characters; that is, characters which need not be 
of a numerical nature. Thus, the PET's string facilities allow the programmer to use strings of 
alphabetic characters and graphical and other symbols in addition to pure numbers. This greatly 
increases the versatility of PET/CBM programs and is fundamental to programs which call for the 
manipulation of words and symbols. 

A string variable is identified by the $ symbol and has many features in common with a numerical 
variable. Thus, typical string variables would be A$, BE$, C8$, etc. Strings may be assigned to string 
variables using the = sign, the string being enclosed in quotation marks. 

Example 4.1 

10 A*="B0G" 
20 B*="CAT" 
36 PRINT A$,B* 
48 END 

At an elementary level strings are very effective in personalizing the computer's response during 
a program. 

Example 4.2 



10 PRINT "WHAT IS VOUR NAME ?" 

20 INPUT A* 

30 PRINT "HELLO "H*".I AM PLEASED TO MEET VOU. " 

i 

i 

i 
100 PRINT "WELL DONE "A*". VOU ARE CORRECT." 

i 

i 

i 
200 PRINT "I AM SORRY "fl*" VOU ARE WRONG. TRY AGAIN." 



4.1 COMPARISON OF TWO STRINGS 

Two strings may be compared with each other by the use of the = sign. If such a comparison is 
incorporated in an IF ... . THEN command this can form the basis of a simple question and answer 
quiz or teaching program. 

37 
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Example 4.3 



itf 



PRINT "["PLEASE TELL ME YOUR NAME" 
29 PRINT 
39 INPUT A* 

49 PRINT "."HELLO "A* 

F,fi FOR J=i TO 1000 :NEXT J 

m B$=" WHICH CITY IS THE CAPITAL OF FRANCE ?" 

70 C*= "PARIS" 

50 PRINT "IT'S* 
90 PRINT 

160 INPUT D* 

110 PRINT 

120 IF D$=C* THEN PRINT "WELL HONE "fl*:END 

138 PRINT "IHO, IT IS NOT "D*".TRV AGAIN": GOTO 98 

It should be noted that, in order for two strings to be judged to be the same, they must be truly 
identical. Thus, the characters must be in the same order and any spaces must also be in the 
corresponding places in each string. This can sometimes present a difficulty because a space at the 
start or the end of a string can be difficult to detect so that the PET may declare two strings to be 
different which, to the user, appear to be the same. A useful technique for detecting these invisible 
spaces is to evaluate the length of the string using the LEN command. Thus, the direct command 
PRINT LEN (A$) results in the number of characters contained in the string A$ being displayed. If 
this is apparently one character too many there is probably a hidden space present. Alternatively, the 
string can be displayed in reverse field in which case the hidden space becomes obvious. 

Two strings may also be compared using the < and > symbols. However, this is misleading 
because it is not the string lengths which are being compared but the magnitudes of the ASCII values 
of the first characters of the string. If the first characters are the same then the next two are compared, 
and so on. Because the ASCII values for the alphabet characters ascend uniformly from A to Z, this 
feature can be very useful for the alphabetic sorting of lists of names and similar applications. 



4.2 CONCATENATION 

Two strings may be concatenated, i.e., joined together end to end, by the use of the + sign. 

Example 4.4 

10 A*="CAR" 
20 B*="HIRE" 
30 C*=fi$+B* 
40 D$=B$+A$ 
58 PRINT C$,B* 
60 END 

Note that there is no space between the two components of the concatenated string and that this 
must be introduced separately if required. Many strings may be joined in a single operation by this 
technique. It is often required that a string be broken down into smaller sub-strings, i.e. the reverse of 
the concatenation process. However, there is no such single process available and this must be 
achieved by the use of one of the following functions. 
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4.3 STRING HANDLING FUNCTIONS 

The string handling functions LEFT$, RIGHTS and MID$ are invaluable when manipulating strings. 
MID$ is particularly powerful. 

LEFTS (A$, N) will extract the first N characters from the string A$, starting from the left hand 
end of the string. These characters can then be assigned to a new string variable, if required. 

Similarly, RIGHT$( A$, N) executes the same function but starting from the right hand end of the 
string. 

Example 4.5 

10 H*="flBCDEFGHIJ" 
20 B$=LEFT$<H$,5> 
36 C*=RIGHT*<H$,5> 
40 PRINT Bf-..C* 
50 END 

Although extremely useful, the above commands are limited in that the starting points of the 
operation, namely the left and right hand ends of the string, cannot be changed. The only variable is 
the number of characters returned. 

A more useful function is MID$. Thus, MID$(A$,N) extracts the Nth and all succeeding 
characters of the string A$ to give a result similar to that produced by RIGHTS. However, a second 
argument may be included in the expression, e.g. MID$(A$,N,P). This has a greater flexibility 
because both the starting point (N) in the string and the number of characters extracted (P) can be 
varied. 

Example 4.6 

10 fl*="RBCBEFGHIJ" 
20 B*=MIB*<fl*,5> 
30 C*=MID*<:fl*,5,3> 
40 PRINT B$,C$ 
50 END 



4.4 SUBSCRIPTED STRING VARIABLES 

If many strings are to be used in a program it is a laborious and rigid process separately to assign each 
string to its string variable. This is made far easier and more flexible if subscripted string variables are 
used. 

A single-dimensional subscripted string variable may take the forms A$(l), A$(23), etc. as 
compared with the non-subscripted forms Al$, A23$, etc. 

A set of subscripted strings may be thought of as an array of variables. This array may be 
one-dimensional, as above, e.g. 

A$(l) 
A$(2) 
A$(3) 

l 

i 
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or it may be two-dimensional, e.g. 

A$(l, 1) A$(l,2) A$(l, 3) 

A$(2, 1) A$(2, 2) A$(2,3) 

A$(3, 1) A$(3,2) A$(3, 3) 

i i i 

I i I 

I ■ ' etc. 

i i ' 

If the array does not exceed 11 subscripts in either direction (i.e. A$(0) .... A$(10) for a 
one-dimensional array) then the PET will immediately accept all the components of the array. If 
subscripts greater than 10 are required it is necessary to dimension the array before it is used. In effect, 
on receipt of a dimensioning (DIM) statement, the machine reserves sufficient space in its memory to 
accommodate the full array. Thus, a statement DIM A$(50) will allow subsequent use of subscripts up 
to 50 A two-dimensional array could be dimensioned as, say, DIM A$(12,15). Failure to dimension 
large arrays results in a break in the program and a BAD SUBSCRIPT ERROR message being 
displayed. 

Subscripted strings are particularly powerful when used with FOR . . . NEXT loops. 

Example 4.7 

19 INPUT 'TENTER NUMBER OF TERMS IN flRRflV";N 

29 DIM fi*<N> 

>:0 B$="*" 

40 FOR P=l TO N 

Fifl H$ <P>=B*+fl*<P-l> 

60 NEXT P 

70 FOR Q=l 10 N 

SO PRINT m<Q':> 

90 NE*T 9. 

100 END 

This program fills a one-dimensional array A$(l) . . . . A$(N) with an increasing number of "*" 
characters. Note the use of the FOR . . . NEXT loop with the generalized variable A$(P) and also the 
use of concatenation in line 50 to increase automatically the number of "*" characters in each 
ascending variable. When the array has been filled completely, lines 70-90 cause the contents of the 
array to be displayed on the screen. The length of the delay between the start of the run and the start of 
the screen display gives a clear indication of the time taken in filling the array. 

This program may also be used to demonstrate the alarming ease with which the memory can be 
filled when using these techniques. If N is set to 300, say, then an OUT OF MEMORY ERROR 
message is soon displayed. The point in the program at which this occurs will depend upon the 
memory size of the particular PET used. On a 32K machine it will be found that the last number of the 
array to be assigned is typically A$(245). If the direct command PRINT FRE(0) is entered to 
ascertain how much memory is still available it is found that there are typically only about 130 bytes 
unused, because of the large number and large size of the strings created. 

To demonstrate the maximum permitted string length, line 30 may be altered to B$ = "**". 
When the program is re-run, with N=300, say, it now stops with a STRING TOO LONG ERROR 
message displayed. The last variable assigned is now A$( 127) which contains 254 characters. The next 
variable, A$(128) would require 256 characters and would thus exceed the maximum permitted 
string character limit of 255. 
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It is clear that a two-dimensional array A$(N,P) will generally fill the memory at a lower value of 
the subscripts N and P than in the corresponding one-dimensional case A$(N) because the number of 
subscripted variables created is N multiplied by P. Thus, care must be exercised when using these 
arrays to ensure that the memory capacity is not exceeded. Higher orders of arrays may also be used, 
e.g. A$(N,P,Q) but they demand even greater care. For example, if N=P=Q=20 the completed 
three-dimensional array will have 8000 elements and, consequently, each element must on average 
not exceed four characters in length if the memory of a 32K machine is not to be over-filled. 

4.5 LABELLING STRING CHARACTERS 

One of the most interesting applications of string handling lies in the analysis and labelling of string 
characters. The most effective way to achieve this is to use the MID$ function together with 
subscripted string variables. 

Example 4.8 

10 A$=" MANCHESTER" 
28 N=LEhKfl*> 

38 FOR F-i TO W 

40 E*'::P>=f1ID*(R*,P,l> 

50 NEXT P 

This program extracts each character in turn from the string A$ and assigns it to a position in the 
array B$(l) . . . B$(10). Thus B$(1) = M, B$(2) = A etc. 

If required, these labelled characters may be re-assembled to reproduce the original string by 
concatenation. 

Example 4.9 

60 REM RE~flSSEMBLV 
70 FOR 0=1 TO H 
88 B$=B$+EI : (Q> 
98 NEXT Q 
108 PRINT B$ 



Note that no DIM statement is required in this program because here LEN(A$), and hence the 
highest subscript, is not greater than 10. 

Once the characters of the string have been labelled they can be displayed individually in any 
order or, alternatively, they can be re-assigned to another array. 

Example 4.10 

18 INPUT 'TENTER WORD" ■ A* 

28 N=LEN(flt> 

.-■ -j- l ! in d i- '■ n .' .' '_• 4- ■, fi . ' 

40 FOR P"l TO N 

58 B * ■■:' P "> =i'1 1 .0$ ! - hi- .. P .. 1 > 

68 f-'RINT "E$<"P" - ! = M B$<P'> 
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86 FOR Q=i TO N 

9fi C$03>=Bf<N+l-Q> 

106 PRINT "C$<"Q">="C*<G> 

il@ NEXT Q 

128 FOR R=l TO N 

130 D*=C*<R>+D* 

140 NEXT R 

150 PRINT D* 

166 END 

Here lines 10-70 label the characters of any string A$ and display the labels individually. Lines 
80-110 re-assign the B$(N) labels to a new array C$(N) in which the label numbers are reversed. 
Lines 120-150 re-assemble the original string from the new C$ array. 

4.6 WORD LABELLING 

The process of labelling the characters of a string may be extended, where appropriate, to the 
identification and labelling of the groups of string characters which make up the words in a sentence. 
To achieve this the above analysis program is modified to search for the spaces which separate 
adjacent words in the string. When such a space is identified the word is labelled as part of a 
subscripted string array. 

Example 4.11 

Ifi PRINT "."ENTER SENTENCES!?}" 

20 input m 

:-:fl N=LEN<fl*>:D=l-'DIM B*<N>:Z*=" " 

48 C=l:REM C=N0,0F WORDS 

5fl FOR P=l TO N 

m IF MIB*<fi*,P,i>=" "THEN 80 

70 NEXT P 

80 B*<C::'=riID*(fl$.-n.-P-D> 

Qfl l!=p+1 

100 IF P<N THEN C=C+l:G0T0 70 

Here, lines 50-70 examine each character of the string in turn, looking for a space. When a space 
is detected the program jumps to line 80 for the word to be labelled. The counter P is then set to P+ 1 
in line 90 (P being the position of the character currently being examined). This has the effect that, 
when the next word is sent to line 80 for labelling, it is not accompanied by the previous word, nor by 
the space between them. Variable C is incremented after each word has been labelled to keep a record 
of the number of words in the string. When the complete string has been examined all the words of the 
string have been stored in the subscripted array B$(l) .... B$(C). 

The words can later be re-assembled, as in lines 120-160. 

Example 4.12 

120 REM RE-flSSEMBLE 
130 FOR Q=l TO C 
140 B*=B*+E$<Q>+Z$ 
150 NEXT Q 
160 PRINT B$ 
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Line 140 re-builds the original string from the labelled words which are concatenated together 
with spaces (Z$) inserted between them. 

It is now possible to re-assemble the string with a different word order. 
Example 4.13 

188 REM RE-fiSSEMBLE REVERSED 

196 PRINT "IT 

280 FOR R=l TO C 

2 1 C*=2$+B* < R > +C$ 

220 NEXT R 

230 PRINT C$ 

Here the original word order is reversed by the use of line 210 instead of line 140. 

Another possible re-arrangement of the words is to sort them alternately into two sets, here 
denoted by printing alternate words in reverse field. 

Example 4.14 

250 REM SELECT ALTERNATE WORDS 

260 PRINT "IT 

2?fl .T±= n g" :K*="S" 

280 FOR S=l TO C-'IF INT-::S/2>=S/2 THEN B$(S>=J*+B$<S>+K* 

298 B3 : =D$+B*<:S>+Z* 

300 NEXT S 

310 PRINT D$ 

320 END 

In this case where the word label, i.e . the current subscript of B$( 1 ) . . . . B$(C) , is exactly divisible 
by two [so that in line 280, INT (S/2) = S/2], then the reverse field string, J$, is added to the word 
before it is displayed on the screen. Note that, although the reverse field is automatically switched off 
by the return at the end of line 280, it is good practice to include the "reverse field off" string K$ to 
avoid modifying any subsequent words unintentionally. This reverse field modification is not easily 
removed because there is no reverse of the concatenation procedure. If the word is needed again in its 
original form it is better to make a copy of it in some other string variable before J$ is added. 

The complete program is shown below with the addition of lines 110, 170 and 240, which provide 
pauses until a key is pressed, to separate the different sections of the program. 

Example 4.15 

1@ PRINT "."ENTER SENTENCEWW" 

28 INPUT m 

38 N=LEN<fl*):D=l:DIM B* < N ) = Z*= " " 

40 C=1=REI1 C=N0.0F WORDS 

50 FOR P=l TO N 

60 IF MIMKfi*,P,i> = " "THEN 80 

70 NEXT P 

89 B*<C>=MID*<fl*,D,P-D> 

90 D=P+1 

100 IF P<N THEN C=C+1 :G0T0 70 

110 PRINT "3": GET E*=IF E*=""THEN 110 

120 REM RE-ASSEMBLE 
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136 FOR Q=l TO C 

148 B$=B*+B*<Q>+Z* 

150 HEKT Q 

16U PRINT E$ 

170 GET E*:IF E*=""THEN 170 

ISO REM RE- ASSEMBLE REVERSED 

190 PRINT "D" 

200 FOR R=l TO C 

210 Cf=Z$+B$<R)+C* 

220 NEXT R 

230 PRINT C* 

240 GET E* : IF E*=""THEN 240 

250 REM SELECT ALTERNATE WORDS 

260 PRINT "IT' 

27« .T*="a" :K*="B" 

280 FOR S=l TO C:IF INT(S/2>=S/2 THEN B$CS>=Jf +B* < S > +K* 

290 m=m+B$<S>+Z$ 

300 NEXT S 

310 PRINT D* 

320 END 

An alternative ending to the program can be substituted after line 150: 

Example 4.16 

10 PRINT "CENTER SENTENCEWW" 

20 INPUT m 

30 N=LEN<fl*>:D=l:DIMB*<N>,C*<N):Z*=" " 

40 C=1-REM C=NO.OF WORDS 

50 FOR P=l TO N 

68 IF MIM<A*,P,i::' = " "THEN 80 

70 NEXT P 

80 B*<C>=MID*<fl*,D;P-D> 

30 ii=p+l 

100 IF P<N THEN C=C+1=G0T0 70 

110 PRINT "3" -GET E*-IF E*=""THEN 110 

120 REM RE-flSSEMBLE 

l:-:fi FOR P=l TO C 

140 B$=B$+B$<Q)+Z$ 

150 NEXT Q 

160 PRINT "IT 

1 70 J*= " SI" = K*= " 1" ■• PR I NT J*+B*+K* 

ISO PRINT "WWIDENTIFV THE PARTS OF SPEECH" 

190 FOR R=l TO C 

200 PRINT "SWORD NUMBER "R"="; = INPUT F$ 

210 C*<R)=F* 

220 NEXT R 

230 PRINT "IT 

24fi FOP S=0 TO C-l 

250 PRINT B$<S+l)SPCa5-LEN'::B$<S+l;0>"IS fl "C*CS+1> 

260 PRINT 

270 NEXT S 

230 END 

This demonstrates how, once the words have been labelled, they may have further labels attached 
to them. 
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4.7 WORD SEARCHES 

String functions may be used to identify specific words or characters in a sentence. 

Example 4.17 

10 DIM B$<80) 

28 PRINT ".TENTER KEYWORD •• - ";■ INPUTS* 
30 PRINT "TENTER SENTENCES^" 

48 INPUT m 

58 N=LEN<flf> :D=1 

fifl FfiR p=j JO N 

78 IF !-'iID±<flf,P,i) = " " THEN 98 

38 NEXT P 

98 IF MID|:<R*,D,P-D>=K$ THEN 150 

188 D=P+1 

118 IF P<N THEN 88 

120 PRINT "TSTHE KEVWORD IS NOT PRESENTS" 

138 PRINT "MAIN THIS SENTENCE!" 

14 Pi fifiTO 160 

158 PRINT "SSTTHIS SENTENCE CONTAINS THE KEV WORDS" 

168 FOR J=l TO 2088 : NEKT J 

17*0 GOTO 30 

Here, the same word-analysis procedure as used previously is employed in lines 50-100 with the 
difference that, instead of a word being labelled and placed in a subscripted array, it is simply 
compared with the keyword X$ in line 90. A simple modification could be added to this program to 
count the number of times the keyword occurs. 

An alternative word-identification technique allows a series of data statements to be scanned for 
a keyword. This may be extended to the association of the identified keyword with preceding or 
subsequent data. 

Example 4.18 

IS INPUT "."ENTER KEV CONDITION";** 

29 READ A*: IF A*="*" THEN 68 

38 IF LEFT*-:: fit, 1) = "-" THEN Z*=A* : V=V+P REM V=TOTflL PATIENT COUNT 

48 IF A*=X* THEN 88 

Sfl GOTO 28 

60 IF D=8 THEN PRINT "SSKEV CONDITION NOT PRESENTERS" : GOTO 148 

?fi r-ifiTO 1 1 

30 IF D=0 THEN PR I NT " 33" X*" PATIENTS!" 

90 PRINT "MPfiTIENT:"Z*:D=l-X=X+i :REM X=C0UNT OF KEV CONDITION PATIENTS 

100 GOTO 20 

110 PRINT "M3THAT IS ALL!" 

120 PRINT "MNUMEER OF "X*" PATIENTS="X 

130 PRINT "SMJMBER OF PATIENTS ON FILE="V 

140 PRINT "WWSPRESS THE SPACER TO CONTINUES" 

156 GET E*:IF E*<>" " THEN 158 

1 m RESTORE : D=8 : X=0 : V=8 : Z*= " " : GOTO 1 

170 DATA -CQCKROFT S.M. , EPILEPSV, -COLEMAN S. ..RHEUMATISM.. BRONCHITIS 

130 DATA DIABETES, -COUGHLAN F.W. ..ANGINA, STROKE, -CROMPTON A. , RHEUMATISM 

19fi DATA -DAWSON C. ..LUMBAGO, -DENNIS H. , STROKE, -DOL AN J. C. , CANCER, THROMBOSIS 

pm DATA -DPI VEP J . , ERONCH I T I S , D I ABETES , -DURHAM E . , CANCER , -ECCLES C . A . , ANG I NA 

210 DATA -EMERV G. ..MIGRAINE, LARVNGITIS, -FELL P. H. ..ANGINA, -FIELDING E., LUMBAGO 

220 DATA -F I Tf:H L , . PNEUMON I A , ERONCH I T I S , -GATCHET A . , BROHCH I T I S , THROMBOS I S 

230 DATA -HAPTsIDE F. .STROKE, -GEE E. ..CANCER, -GILES G.S. , MIGRAINE, RHEUMATISM 
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?4fl DATA -nRHflN -T. P. ■ EPILEPSV, RHEUMATISM, DIABETES.. ANGINA, LUMBAGO, STROKE, CANCER 
5-W DATA BRriNHH 1 1 1 S , LARVNG I T I S , M I GRA I NE , PHEUMON I A , THROMBOS I S , PLEUR I S V , SC I AT I UH 
oi,n nflTA -HAMPSON I . , BROHCH I T I S , -HARL I CK G . , D I ABETES , THROMBOS I S , -HARR I S V . E . 
270 DATA PLEURISV,-HIBBERT H. , RHEUMATISM, SCI AT I CA, -HOLL I NDRAKE J-i^TRuKE 
owi DATA -.TflCKSflN N. .CANCER, LUMBAGO, -JONES R. , CANCER, -KELLV U. ,DIHEETE.:.,.;.TRUKE 
3q« r, fiTfl -KNflWLES H. , BRONCHITIS, -LflIHE A, LUMBAGO, PNEUMONIA, BRONCHITIS, ANGINA 
300 DATA -LAWTW T . . SC I AT I Cfl , -LOHGDEN E . , THROMBOS I S , ANG I NA , -MACKRELL H . , STRUKE 
T;ifl DflTfi -pflpKEP .T.', CANCER, -PEARSON A. ..DIABETES, -QUINN P.J. , LARVNGITIS, ANGINH 
328 DATA -RAMSDEN S. ..BRONCHITIS, PNEUMONIA, -WILLIS J. T.R. ..DIABETES, RHEUMATISM 
336 DATA * 

This is a program to identify the patients in a doctor's files who suffer from a particular illness. 
The patients' names are identified by a preceding hyphen. The keyword is supplied in line 10 and 
stored as X$. The data statements containing the patients' names and their various ailments are 
scanned in lines 20-50. Each time a data statement preceded by a hyphen is encountered the patient 
count, Y, is incremented and the patient's name is stored temporarily in Z$ (line 30). When the key 
illness X$ is detected the current value of Z$ gives the name of a patient suffering from this illness. 
This name is displayed on the screen and the search continues until the data entry "*" is read which 
terminates the search. D is a flag which is set the first time the keyword is identified and is used to 
dictate the form of the screen display. Note the necessity for the command RESTORE in line 160 
before the data base can be re-entered for a new search. Note also that it is not necessary to use 
subscripted strings with their associated complication of DIM statements and their voracious use of 
memory space. This is because the data are not labelled and stored for future use, the temporary store 
Z$ being all that is required. 

In this simple form of search program the process is limited only by the size of the available 
memory. Typically 1000 patients and their ailments can be handled on a 32K machine. A more 
realistic approach would be to store the data base on a disk file, sections of which would be 
periodically transferred to the PET for the searching process. 

As a final exercise it is interesting to use some of the techniques already discussed to write an 
"anagrammatizer" program in which a word is picked at random from a data base and scrambled. One 
possible solution is shown below together with additional program statements which make it the basis 
of a game whereby the player's guess is compared with the original, unscrambled, word. 

Example 4.19 

10 PRINT "3 ANAGRAM TIME !" 

20 DIM W*<lfi5> : DIM RC30::' : DIM BSCSO; 1 : BIM CSCSO;' 

30 REM flsSIGN DATA WORDS TO W$Q ARRAV 

40 FfiR P=l TO 185: REM 185 = NUMBER OF WORDS IN THE DHTH EH*E 

50 READ W*(P) 

h0 HEKT P 

70 PRINT "H" 

30 Z=RNDC-TI): REM RANDOM SEED 

99 REM CHOOSE A WORD TO ANAGRAMMATIZE 

100 Z=INT(18fe*RNDa::0 
110 A*=W*<Z? 

128 REM LABEL LETTERS OF WORD AS B*a..N> 

130 n=len<:a*> 

140 FOR Q=l TO N 

150 B*<Q)=MID*<fi*,Q,l> 

160 NEXT Q 

170 C*="" 

lft p, PFINT'TIPUIET PLEASE ! IIIIHIIIIIIUHMHHffill AM RNAGRAMMATIZINU 

196 REM CHOOSE A RANDOM LETTER POSITION 

200 FOR S=l TO N 

210 R=INT«N+1)*RND<1>> 

220 IF R=@ THEN 210 

230 REM SET FLAG W IF THIS POSITION HAS BEEN USED BEFORE 
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248 FOR T=l TO N 

256 IF R=R'::T>THEN W=i 

260 NEXT T 

270 REM POSITION ALREADV IJSED.TRV AGAIN 

289 IF W=l THEN W=0 : GOTO 218 

2 c,fi pEM ASSIGN STH. POSITION IN SCRAMBLED WORD TO RTH. LETTER IN 

308 REM ORIGINAL WORD 

:~: 1 n CtiS'>=B$iR':> 

320 REM RECORD THAT RTH. POSITION HAS NOW BEEN USED 

330 RCS.- I= R 

348 NEXT S 

350 REM RE-ASSEMBLE SCRAMBLED WORD 

360 FOR U=l TO N 

37a C*=C$+C$<U> 

3S0 Ri:'U>=0 

390 NEXT U 

4FiO PEM TRV AGAIN IF SCRAMBLED WORD=ORIGINAL 

410 IF C$=A* THEN 178 

420 REM PRINT SCRAMBLED WORD 

438 PRINT'TJTHE ANAGRAM IS S"C*"i" 

440 PRINT"J!M«WHAT IS THE ORIGINAL WORD ?" 

450 PR I NT "MS": INPUT D* 

46fi IF D*=A$ THEN PRINT "IXORRECT ! WELL DONE": GOTO gog 

470 PRINT "^NO! THAT IS NOT CORRECT" 

4*0 PRINT "MSMBWOULD VOU LIKE TO TRV IT AGAIN ?" 

490 PRINT "MC PLEASE ANSWER V OR t-D 

500 GET E*:IF E*="" THEN 580 

518 IF E$="V" THEN 548 

528 IF E*="N" THEN 598 

5:-:fi fifiTii 500 

54fi PRINT "MMS3HALL I RE-ARRANGE THE WORD ? (V OR H>" 

5^0 GET F*:IF F*="" THEN 558 

l=;60 IF F*="V" THEN PRINT "3": GOTO 130 

570 IF Ff="N" THEN PRINT "IT: GOTO 410 

538 GOTO 55y 

590 Ji=":J" 

608 F$=J*+A* 

618 PRINT "."FILL RIGHT. I WILL TELL VOU" 

62fl PRINT "WTME WORD WAS "F* 

630 PRINT "SWWWWOULD VOU LIKE ANOTHER WORD ?" 

648 PRINT "W, PLEASE ANSWER V OR N)" 

650 GET E* : IF E*="" THEN 650 

660 IF E*="V" THEN 100 

678 IF E*="N" THEN PRINT "[TTHANK VOU FOR FLAVINGSMsftftMSsM" : END 

6:-:fi Gfijfi 650 

698 DATA ABSENCE , ACCEPT , flCC I DENTALLV 

I 

I 

I 

I 

and so on. DATA statements containing an additional 182 words are added to make a total of 185 
words (line 40). 
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Sorting Words and 
Numbers 



INTRODUCTION 

Sorting lists of numbers into numerical order or lists of names into alphabetical order is a dreary task 
which is better performed by a computer. There are many different sorting routines available in 
which, generally, complexity may be traded off against speed. 



5.1 BUBBLE SORT 

The simplest and probably the most widely used routine is the bubble sort. This is so called because the 
smallest number appears to 'bubble' to the top of the list. Bubble sorts are very widely employed 
because of their simplicity. 

In a numerical bubble sort a list of numbers is repeatedly scanned from top to bottom. On each 
pass each number is compared with the one below it. If it is smaller than the one below, it is left alone; 
if it is larger the two numbers are interchanged and the scan proceeds to the next number, (which, of 
course, will be one of the numbers just interchanged.). It can be seen that, after the first pass, the 
largest number will be at the bottom of the list. A second pass will leave the next largest number in the 
next to the bottom position and so on. At first it appears that to be certain that a list of N numbers has 
been completely sorted N-l passes would be needed. However, this lengthy procedure may be 
shortened. It is not necessary to include every number in each pass. Thus, it would be pointless to look 
at the last number on the first pass because it is already in place. Similarly for the next to the last 
number on the second pass etc. Thus, each pass contains one less comparison than the previous one. 

Also, if the original list is randomly arranged, then by chance all the numbers may be in order 
before the (N-l)th pass, in which case further passes are unnecessary. Thus, if on any pass it is found 
that no interchanges were necessary, the sort may be terminated. 

A simple bubble sort is shown in Example 5.1, where ten numbers are sorted into numerical 

order. First the numbers are read from data statements into the array A(l) A(10) and at the 

same time they are printed on the screen (line 40). The sort proper starts in line 60 where X is set to 
N-l, the number of passes expected. In line 80 Y is set up representing the number of comparisons 
made in each pass and on each successive pass the range of Y is decremented by 1. The number of 
comparisons made is counted and stored in the count variable C in line 90. Adjacent numbers are 
compared in line 100. If they are in order then a jump is made to 160 to start the next comparison. If 
not, an interchange is made in 130-150, a flag Z is set to 1 to show that an interchange has occurred 
and the interchange counter E is incremented. At the end of the pass line 170 checks flag Z. If it is zero 
then the data must be in order and the sort can be terminated. If it is a 1 then the next pass is initiated. 

If not previously terminated the sort is ended when the (N-l)th pass has been completed. 
Although not strictly part of the sort, the timing variables Tl and T2 and the comparison and 
interchange counters C and E give useful indications of the efficiency of the process. 

51 
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Example 5.1 

1 REM *** BUBBLE SORT *** 

18 READ N :REM NUMBER OF ENTRIES 

20 DIMAOO 

30 PRINT 'TKUNSORTED LIST:-M" 

40 FOR X=l TO N=REflD A<X> :PRINTA<X>: :NEXT X 

50 T1=TI 

60 FOR X=l TO N-l 

70 Z=9 

80 FOR V=l TO N-X 

90 C=C+1 

100 IF RCV+l) >= fl<V) THEN 168 

110 Z=l :REM FLAG SET IF DATA NEEDS TO BE INTERCHANGED ON THIS PASS 

120 E=E+1 

130 N=fl<V) 

140 fl<V)=fl<V+l) 

150 ACV+1)=W 

160 NEXT V 

170 IF Z=0 THEN 290 'REM DATA IN ORDER? 

180 NEXT X:REM START ANOTHER PASS 

190 REM SORT COMPLETE 

208 T2=TI 

210 PRINT: PR I NT "PORTED LIST^-M" 

220 FOR X= 1 TO N: PRINT A(X>: : NEXT X 

230 PRINT 

240 PRINT"MSNUMBER OF COMPARISONS =",C 

250 PRINT"MNUMBER OF INTERCHANGES =";E 

260 T= . 1 * I NT <1 00* <. T2-T 1 ) /68 > 

278 PR I NT "WT I ME TAKEN ="T" SECONDS" 

280 DATA 10 

298 DATA 8 .•€...€■ , 3 , 7 , 2 .• 5 .■ 4 .. 9 , 

300 END 

As can be seen, the bubble sort is very quick for relatively small lists, but as the size of the list to be 
sorted increases, the sorting time becomes much longer. This is demonstrated in Example 5.2 which is 
exactly the same sort as the previous example, but this time sorting an array of randomly generated 
numbers. If N is set to 100, a typical analysis at the end of the sort might be:- 

NUMBER OF COMPARISONS = 4935 

NUMBER OF INTERCHANGES = 2475 

TIME TAKEN = 170.53 SECONDS 

Because of the ability of the bubble sort to cut short its routine if the list becomes ordered before 
the (N-l)th pass, it is difficult to estimate the time required for the sort. Bubble sorts perform best 
when the data are already partially ordered. Thus, if the data are ordered after the first pass, only 
(N-l) comparisons have to be made. But, if the list is in reverse order, the (N-l) comparisons will only 

place the highest value at the end of the list and further passes of length (N-2), (N-3), 2, 1 are 

needed. So the maximum sort effort is N(N-l)/2. On average, for a randomly ordered list, the sort 
effort will be N(N-l)/4, or, for large N, approximately N 2 /4. 

Example 5.2 

1 REM *** BUBBLE SORT *** 

10 PRINT".! SBUBBLES 3B0RTS" 

20 INPUT "SMHOW MRNV NUMBERS TO SORT " .; N 

30 DIM fiCH> :E=0:C=0 

40 : 

50 REM*** PUT UHSORTED NUMBERS IN flRRAV *** 

60 : 

70 GOSUB 550 

90 REM *** PRINT THE UNSORTED flRRAV *** 

1 00 : 
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118 PRINT "MTHE UHSORTED ARRAY IS ■PV 

120 ■■ 

130 GflSUE £fifi 

140 : 

150 REM *** SORT IT *** 

160 : 

17a GOSUB 340 

180 : 

190 PRINT "THE SORTED ARRAY IS -W 

200 : 

210 GOSUB 600 

220 : 

230 PRINT" SBUEBLE" 3SORTB8" 

240 PR I NT "NUMBER OF COMPARISONS =" : 

250 B3=C : GOSUB 740 

260 PR I NT "NUMBER OF INTERCHANGES ="; 

270 B3=E: GOSUB 749 

280 T=. 01*INT( 100*CT2-T1 >/60> 

290 PR I NT "MI' I ME TAKEN ="T "SECONDS" 

300 END 

310 : 

320 REM #** BUBBLE SORT **# 

340 T1=TI 

350 FOR X=i TO N-l 

360 2=0 

379 FOR V=l TO N-X 

380 C=C+1 

390 IF FKY+1) >= FKY) THEN 450 

400 Z=l -REM FLAG SET IF DATA NEEDS TO BE INTERCHANGED ON THIS PASS 

418 E=E+1 

420 w=A'::v:> 

430 a<v>=a<:v+i> 

448 ACt'+1>=W 

450 NEXT V 

460 IF Z=6 THEN 490: REM DATA IN ORDER? 

470 NEXT X:REM START ANOTHER PASS 

480 REM SORT' COMPLETE 

490 T2-TI 

580 RETURN 

510 : 

520 : . 

530 REM*** FILL ARRAY WITH RANDOM NUMBERS *** 

540 : 

550 FOR K=l TO N: A(K> = INTa00*RND';0;O : NEXT K 

560 RETURN 

570 : 

580 REM **'* PRINT ROUTINE FOR TEN COLUMNS *** 

590 : 

600 FOR K=l TO N 

610 Q=K-10*INT<CK-1 >,-'10> 

620 PRINT TAB<4*';Q-1>>; 

630 IF HCKX10 THEN PRINT" ".: 

640 PRINT A<K>; 

650 IF Q>=iO THEN PRINT 

S60 NEXT K 

670 PRINT"*" 

680 RETURN 

698 : 

700 : 

710 REM *** COLUMN ALIGNMENT ROUTINE *** 

720 : 

730 : 

740 B1=0:E2=B3 

750 IF B2<1 THEN 770 

760 B1=E1 + 1-B2=B2,-'10:GOTO 750 

770 PRINT SPC'::6-Bi:'.;B3 

780 PRINT 

790 RETURN 
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This example has been written in the form of a main program with numerous subroutines because 
it is in this form that sort routines are most likely to be used and encountered. Other subroutines, apart 
from the sort subroutine, are concerned with the generation, formatting and presentation of the data. 

Numerical sorting techniques may easily be extended to the sorting of words into alphabetic 
order. Two word strings may be compared using the operators > and <. These operators compare the 
magnitudes of the ASCII values of the first characters of the strings. If these are the same then the next 
two are compared and so on. Because the ASCII values of the alphabet characters ascend uniformly 
from A to Z this gives a true alphabetic sort. Thus CAN will be judged to be "less than" (<) CAR 
which in turn will be "less than" (<) CAT. Care must be taken when including punctuation marks and 
spaces in the strings because these will also be included in the comparison. However, as these all have 
ASCII values less than A the sort is not usually upset. 

Example 5.3 is essentially the same bubble sort as in the previous two examples but modified to 
deal with strings. Thus, it is strings which are read from the data statements in 20-40, strings which are 
compared in 90 and strings which are interchanged in 1 10-130. The time taken for the sort is virtually 
the same as the time taken to sort the same number of numerical elements. 

Example 5.3 

1 REM *** ALPHA BUBBLE SORT *** 
10 READ N :REM NUMBER OF ENTRIES 

29 DIM A*00 

30 PRINT 'TUNSGRTED LIST—M" 

40 FOR X=l TO N=READ fl*<X> : PR I NTA* < X > 'NEXT X 

50 T1=TI 

60 FOR X=l TO N-l 

70 Z=@ 

ftfl FOR V=l TO N-X 

90 IF fl*('V+r> >= fl*<V) THEN 140 „„__ 

100 2=1 ; REM FLAG SET IF DATA NEEDS TO BE INTERCHANGED ON THIS PASS 

110 W*=fl*<Y) 

120 fl*<V)=fl*<V+l> 

130 a*<:v+i>=w* 

140 NEXT V 

150 IF Z=0 THEN 170: REM DflTA IN ORDER? i 

160 NEXT X-REM START ANOTHER PASS 

17« REM SORT COMPLETE 

180 T2-TI 

190 PRINT: PR I NT "SI" SPC < 20 > "SORTED LIST = -J«" 

200 FUR X= 1 TO N : PRINT SPCC20) A* CO : NEXT X 

210 T=. 01*INT< 100#<T2-T1 V60> 

220 PRINT".WTiriE TAKEN ="T" SECONDS" 

240 DATA EMERY G.,D0LAN J. C. , HARRIS V.E...RAMSDEN S. , FIELDING E.,MACKRELL H.R. 
:"=i0 DATA PEARSON A., HARRIS V . J . , L0NGDEN E...HARLICK CLAWTON J., PARKER J. 
260 DATA C0LMAN S. , DENNIS H. ..FELL P. H. , FITCH L.,QUINN P. ,H0LLINDRAKE J. 

Example 5.4 is again a bubble sort but this time the data are extended to cover three subjects or 
fields instead of one. Thus, the first field is a name, the second an age and the third some sort of mark 
or grade signified by the letters A to D. The data are read into a two-dimensional array A$(N, F) in 
lines 30-70, where N is the number of multi-field elements to be sorted and F is the number of fields. 
Thus, in this case, A$( 1 ,1) is SMITH, A$( 1 ,2) is 24 and A$( 1 ,3) is B etc. The contents of this array are 
displayed in 110-160. The bubble sort is then entered at 180 and in 210 the elements are compared. 
However, the comparison can be made in either the 1st, 2nd or 3rd field, depending upon the value of 
K entered in line 90. If, as a result of the comparison, an interchange is required then it is essential that 
all the fields of the relevant element are interchanged together. This is achieved by a FOR . . . NEXT 
loop in conjunction with the normal interchange instructions in 220-260. When the sort has been 
completed the sorted array is displayed. To repeat the sort with a different key field K following the 



SORTING WORDS AND NUMBERS 55 

GET hold in 430, the data statements are read again, this being the easiest way to restore the original 
A$( ) array. This necessitates a RESTORE in 440. (None of this would be needed if the unsorted 
array were not displayed.) 

Example 5.4 

1 REM *** 3 FIELD BUBBLE SORT *** 
10 READ N,F:IF Z2=l THEN 39 
20 DIM H*<N,F> 
38 FOR X=i TO N 
48 FOR J=l TO F 
50 READ H*<X,J> 
60 NEXT J 
70 NEXT X 

80 PRINT "."ENTER KEV FIELD a, 2, 3 ETC.) 
90 GET K:K=INT<K>:IF K=0 OR K>F THEN 98 

1 00 : 

110 PRINT "."UNSORTED LIST" 

120 PRINT " M" 

130 FOR X=i TO N 

140 FOR J=l TO F 

1 50 PR I NT f\$ < X , J > " " .; ■• NEXT J 

160 PRINT: PRINT: NEXT >=; 

170 T1=TI . 

180 FOR X=l TO N-l 

190 Z1=0 

200 FOR V=l TO N-X 

210 IF H$';V+i,rO >= fl$<V,K> THEN 288 

220 FOR P=l TO F 

230 W*=fl$(V,P> 

240 fl$ ■:.' V , P > =fi$ •: V+ 1 , P > 

250 fi$<V+l,P>=W* 

260 NEXT P 

278 21=1 

280 NEXT V 

230 IF 21=6 THEN 318 

300 NEXT X 

310 T2=TI 

320 PRINT 

330 PRINT "SORTED LIST" 

340 PRINT " M" 

350 FOR X=l TO N 

360 FOR J=l TO F 

370 PRINTfmX,J>" "::NEXTJ 

380 PRINT: PRINT: NEXT x 

390 T=.81*INT<188*(T2-Tl>/60> 

490 PRINT i, c3"SPC<250)SPC<258:'SPCa22>"*;EV FIELD="K 

410 PRINT SPC<102>"ST< SECONDS ;' = "T 

420 PRINT "MMMMSPRESS ANY KEV TO CONTINUE"" 

438 GET G*:IF 0*="" THEN438 

440 RESTORE : 22=1 ; GOTO 10 

450 DflTfi 4,3 

468 BATH SMITH, 24, B, JONES, 43, H, HDflMS, 65, D, BROWN, 42, C 
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5.2 INDEXED SORT 

An alternative technique for sorting multi-field arrays is to assemble a control array in parallel with 
the data array. Numbers in the control array are manipulated as a result of sorting comparisons made 
in the key field of the data array. At the end of the sort the control array determines the order in which 
the elements of the data array are presented. This technique avoids the necessity to move all the fields 
in the data array together during interchanges. Example 5.5 demonstrates this approach using the 
same data as in the previous exercise. The data are read into the array A$( ) as before but in lines 1 1 
to 130 the key field, K, is stripped off into another array C$( ). The sub-routine at 330 assembles the 
control array Y( ). The contents of this array indicate the positions in the key field array C$( )of the 
smallest element, the next smallest element and so on. Thus, if K is 2, and hence C$(l) = 24, 
C$(2)=43, C$(3)=42 and C$(4)=65 then, on leaving the subroutine, Y(l) = l, Y(2) = 3, Y(3)-2 and 
Y(4) = 4. This array now controls the order of print-out of the main array A$( ) in 180-220. 

Example 5.5 

1 REM *** 3 FIELD INDEXED SORT *** 
10 READ N,FIHM fl*<N,F>, C*«:H> , VCN) 

29 FOR X=l TO N 

30 FOR J=l TO F 

40 read h* ';;»:.. J > 

56 NEXT J 

60 NEXT X 

70 PRINT'TENTER KEV FIELD Q,2,3 ETC. > 

80 GET K:K=IMT<K>:IF K=0 OR K>F THEN SO 

90 ■' 

100 T1=TI 

110 FOR X=l TO N 

120 C$<X>=fl*<X,IO 

130 NEXT X 

14fi nnsljE 3o0 

150 T2=TI 

ISO PRINT "I3S0RTE D LIST " 

170 PRINT " M" 

180 FOR X=l TO N 

190 FOR J=l TO F 

200 PRINT fl$<V<X>,J>.:" " ; : NEXT J 

210 PRINT: PRINT 

220 NEXT X 

230 PRINT":«S2KEV FIELD ="K 

240 T=.01*INTaO0*<T2-Tl>/60> 

250 PR I NT "MSTK SECONDS) ="T 

26fl PRINT"MWWWSPRESS flNV KEV TO CONTINUES" 

270 GET G*:IF G* ="" THEN 270 

280 : 

290 GOTO 7@ 

310 REM **# ASSEMBLE CONTROL flRRRV ### 

:-20 : 

330 FOR P=l TO H 

340 M=l 

350 FOR Q=l TO N 



360 


IF C$ ■:. P > >C$ <Q> 


370 


IF C*<P>=Cf(Q> 


380 


NEXT Q 


390 


V'::M>=P 


400 


NEXT P 


410 


RETURN 


420 




430 


DATA 4.. 3 


446 


DATA SMITH, 24, 
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THEN M=M+1 

AND P>Q THEN M=M+1 



B , JONES , 43 , fl , ADAMS , 42 , D , BROWN , 65 , C 
N.B. In both of the two previous examples the arrays to be sorted are string arrays even though 
some of the fields are numerical. Thus, if a numerical field is the key field, it will be sorted as a string 
field. This is satisfactory as long as all the elements have the same number of digits. If this is not so then 
sorting errors will occur. Thus 8 would be judged to be greater than 42 because, in a string 
comparison, only the first characters are compared initially. In such cases it is therefore necessary to 
include leading zeros e.g. 08 so that all the elements are of the same length. 

5.3 INSERTION SORT 

As the name implies, the insertion sort works on the principle of scanning a list of elements and 
inserting a new element in its correct position. Thus, elements from one array may be inserted into 
another array. Alternatively, elements may be fed in from the keyboard as input statements and 
inserted into their correct position, often in a time less than that required to type in an entry. A simple 
insertion sort is shown in Example 5.6. When a new element B$ is encountered in line 50 it is 
compared in turn with all of the existing elements of A$( ). Thus, in 60, B$ is compared with the Lth 
element of A$( ). If it is greater than or equal to A$(L), then L is simply incremented in 70 and, if 
there are any elements of A$( ) left, the comparison is repeated. If B$ is less than A$(L), then it must 
be inserted. In order to make room for it, all the lower values of A$( ) must be moved down. This is 
done in 90- 1 1 and the insertion is made in 1 20. If B$ is greater than all the members of the array, then 
it must be placed at the top of the list in the A$(N) position. To do this the entry is placed above the top 
of the list by setting L to N+ 1 in line 80 and then the whole of the array is moved down to make room 
for it. When all N of the entries have been inserted the assembled array is displayed on the screen. 

Example 5.6 

1 REM *** INSERTION SORT *** 

10 INPUT "HMO. OF ENTRIES" ;N 

20 IF HMO THEN DIM B$OD 

36 FOR K=l TO N 

40 L~l 

50 PRINT "MENTRV NO. "K; • INPUT B* 

60 IF B*<fl*<L> THEN SO 

?6 IF L<N THEN L=L+1=G0T0 69 

80 L=N+1-REM B*> ALL fl*<N) 

90 FOR P=i TO L-2 

I 08 fl* < P .'■• ~fi$ '• P+ 1 > 

1-0 NEXT P 

120 fl$(L-i;-=B* 

130 NEXT K 

140 PR I NT M" 

150 FOR K=l TO H 

160 PRINT"W"fl*<K) 

170 NEXT K 

ISO END 
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5.4 SHELL SORT 

As has been shown, a bubble sort rapidly gets out of hand when the number of elements to be sorted is 
large. However, if the data are not badly out of order initially, a bubble sort may be completed rapidly. 
A Shell sort makes several passes through the data before the final pass, which is in effect a bubble sort 
pass. Each pass orders the data to a higher degree. Whereas a bubble sort compares only adjacent 
elements, a Shell sort initially makes comparisons between elements which are far apart in the array 
on the assumption that the further apart the elements the more 'efficient' will be any corresponding 
interchange of data. With each successive pass the distance between the elements compared is halved 
until the final pass compares adjacent elements i.e. a bubble sort. 

A typical Shell sort is shown in Example 5.7. The framework of this program is the same as in 
Example 5.2 so it is only necessary to consider the sort itself in lines 340-500. The sort interval V, 
which is the element separation over which the comparisons are made, is set up by initially setting V to 
equal N, the total number of elements and then re-setting V to INT( V/2) . Thus, the initial sort interval 
is close to half the total number of elements. A total of (N-V) FOR . . . NEXT loops are then set up in 
390 and in 420 the comparisons are made between elements separated by V. Any subsequent 
interchanges are made in 440-460 and flag Z is set to 1 before 480 initiates the next comparison. 
When all the comparisons have been made, if flag Z is set the comparisons are all repeated (line 490). 
This is because it is not possible to predict when a sort at a given sort interval will terminate. The 
process continues until line 490 finds Z=0 which shows that the elements are in order at the current 
sort interval. The sort interval must now be halved by returning to 360 but first the interval V is 
checked in 350, because if it is unity the sort is complete. If V is greater than 1 then it is halved in 360 
and the sort repeated at the smaller sort interval. Thus, supposing N were 16, the initial value of V 
would be 8 to give an 8-sort, followed by a 4-sort, a 2-sort and finally a 1-sort, which is effectively a 
bubble sort. After the 1-sort is successfully completed the elements must be in order and the sort is 
exited from line 350. 



Example 5.7 

326 REM #** SHELL SORT #** 
: :: : :fi : 

|:4@ V=1LT1=TI 

vm IF V<"=i THEN T2=TI= RETURN :REM SORT COMPLETE 
360 V= INK V/2): REM y=S0RT INTERVAL 
370 L=H-V 
: ;: : :P1 Z=0 

390 FOR J=l TO L 
400 P=J+V 

410 f:=r:+i:REM C=N0.0F COMPARISONS 
420 IF fl(JX=fl(P) THEN 480 
4>:0 E=E+1=REM E=N0.GF INTERCHANGES 
440 W=ACJ:j -REM INTERCHANGE DATA 
450 A';J)=A<P) : 

478 Z=i"' = REM FLAG SET IF DATA NEEDS TO BE INTERCHANGED ON THIS PASS 
4S0 NE y T T 

Iqa if'Vh! THEN :-::=:0:REM REPEAT THE SORT WITH SAME SORT INTERVAL 
500 GOTO" 350 :REM REPEAT THE SORT WITH A SMALLER SORT IHTERVHL 



The Shell sort is thus more complex than a bubble sort and for small values of N may even be 
slower. However, the sort effort for the Shell sort is proportional to N 1 5 compared to the N 2 of a 
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bubble sort with the result that for large values of N the Shell sort is considerably quicker. Thus, if N is 
set to 100 in the present program a typical analysis at the end of the sort would be:- 

NUMBER OF COMPARISONS = 2596 
NUMBER OF INTERCHANGES = 425 
TIME TAKEN = 77.4 SECONDS 

which is typically twice as fast as the bubble sort. 

5.5 QUICKSORT 

Quicksort is the most complex of the techniques discussed here but it generally gives the fastest 
performance, particularly for large values of N. Its sort effort is proportional to NlogN which is 
superior to the sort effort of bubble and Shell sorts, for large numbers. In principle, Quicksort 
operates by splitting the main sort into a number of smaller sorts which in turn are split into even 
smaller sorts until the number of elements in the sub-groups is small enough for bubble sort to be 
efficient. One of the problems is that only one sub-sort can be executed at a time and so the location of 
the other sub-groups to be sorted must be 'memorized'. This is done by storing the start and end 
locations of the sub-groups in a special array called a 'stack'. The stack operates as a 'last-come, 
first-served' storage system. As each sub-group is sorted the boundaries of the next sub-group are 
'pulled' off the top of the stack. When the stack is empty and all the sub-groups have been sorted the 
sort is complete. 

The sort itself employs two pointers which are conventionally identified as I and J. At the start of 
the sort these are initialized to opposite ends of the complete array. Consider the array:- 

45 61 14 8 85 54 23 39 

Initially, pointer I would be associated with 45 and pointer J with 39. The element 45, being the 
left-most entry, is arbitrarily made the reference point of this part of the sort and is called the 'sort 
pivot'. The elements associated with pointers I and J are now compared and if necessary are 
interchanged. Thus in this case the array becomes:- 

39 61 14 8 85 54 23 45 

The sort pivot is still 45 but is now on the right and is associated with pointer J. The pointer 
opposite the sort pivot is now moved towards the sort pivot. Thus, in this case I moves from 39 to 61. 
The process is now repeated. The pointers therefore continually move towards one another and will 
eventually coincide. When this happens, the pointers mark the present position of the sort pivot and 
this is its correct position in the array. The array is now split into two sub-groups by the sort pivot. 

The array now looks like;— 

39 28 14 8 45 54 85 61 

and it can be seen that the 45 is in its correct position. The positions of the 54 and the 61 are now 
pushed on to the stack so that the right-hand sub-group can be sorted later and then the left-hand 
sub-group is sorted by the same technique as above, 39 becoming the new sort pivot. 

An example of Quicksort is shown in Example 5.8. Again the framework is the same as in 
Example 5.2 and the sort itself is situated in lines 340-500. The only modification to the main 
framework is in line 30 where the data array is, as usual, dimensioned to N and in addition the stack 
array S( ) is dimensioned to (20,2). Thus 30 DIM A(N), S(20,2):E = 0:C=0. This is a compromise 
value. Clearly, if very large arrays are to be sorted these limits will have to be increased. If the 
dimension limit of S( ) is exceeded, then the program will terminate in 450 with a STACK 
OVERFLOW error message. In lines 340-350, the pointers I and J are initialised to the first and last 
elements of the array respectively. H is an indicator variable which takes a value of -1 when pointer I 
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indicates the sort pivot and a value of + 1 when pointer J indicates the sort pivot. The comparison of 
elements is made in 370. If no interchange is needed, i.e. if A(I) is less than or equal to A(J) then a 
jump is made to 410 where either I is incremented or J is decremented, depending on the sign of H 
which indicates the position of the sort pivot. If an interchange is required then a simple bubble sort 
switch is made in 390 followed by a change in the sign of H in 400 and again a change in the pointers I 
and J. The pointers are then compared in 430. If I is less than J, then the pointers have not yet 
coincided and the sort continues within the same group. If the pointers coincide then, if 1+1 is not 
greater than J 1, i.e. if the (correctly positioned) sort pivot is not the largest number in the array, then it 
will be necessary to push the boundary pointers of the upper sub-group on to the stack. This is done by 
incrementing the stack counter P and then feeding 1+ 1 and J 1 on to the stack in 460. The sub-array 
boundaries are then set to those of the lower array in 470 and the sort resumed. When all the lower 
sub-groups have been sorted the stack counter is tested in 480. If it is not zero then the most recent 
upper sub-group is pulled off the stack (line 490) and sorted. This continues until the stack is empty 
(P=0) when the sort routine is exited from line 480. 

Example 5.8 

320 REM *** QUICK SORT *** 

330 : 

340 Il=l-Jl=N:Ti=TI 

350 I— II : J= J 1 : H=- 1 : REM SET PO I NTERS 

360 C=C+l:REM C=N0.OF COMPARISONS 

370 IF fl(IX=fl<J) THEN 410 

380 E=E+1=REM E=N0.0F INTERCHANGES 

390 W=H<I> ; A<I>=H<J> :R<J>=W 

410 IF H=l THEN 1=1+1 :G0T0 430 

420 J=,T-1 

439 IF KJ THEN360 

440 IFI + 1XT1 THEN 470 

450 P=P+l:IF P>20 THEN PRINT'TETACK OVERFLOW": END 

460 S •:. P , 1 ) = I + 1 : S i P , 2 > =,T 1 : REM PUSH ONTO STACK 

470 Jl=I-l:IF I1CJ1 THEN 359 

480 IF P=0 THEN T2=TI : RETURN 

490 I1=S<P,1>:J1=S<P,2>:P=P-1 :REM PULL OFF STACK 

500 GOTO 350 

The Quicksort usually gives very satisfactory results, as can be shown by setting N to 100 in this 
program. A typical analysis at the end of the sort would be:- 

NUMBER OF COMPARISONS = 667 

NUMBER OF INTERCHANGES = 209 

TIME TAKEN = 32.8 SECONDS 

This is typically twice as fast as the Shell sort and possibly four times faster than the bubble sort, 
assuming randomly presented data. However, when N is small the extra complexity of the Quicksort 
can be a disadvantage and the sort may be slower than other less complicated techniques. 



CHAPTER 6 
Good Programming 
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Good Programming 



It is relatively easy to learn to write working programs in BASIC. However, the nature of the language 
is such that it is also very easy to write extremely bad programs, which are unintelligible to anyone 
reading the listing, and very difficult to modify. 

Some purists would argue that it is impossible to write really good programs in BASIC, and 
indeed the lack of certain facilities available in other high-level programming languages makes the 
writing of long BASIC programs - several hundred lines or more - very difficult. Nevertheless, if a few 
simple principles are applied, it is possible to produce reasonably well-constructed programs which 
are reasonably intelligible and easy to modify. 

The most important requirement is that the program should be well-designed - i.e., the flow of 
ideas through the program should be simple, straightforward, and easy to follow. This is often quite 
difficult to achieve but is worth a fair amount of effort, since some time devoted to thinking about the 
problem at the design stage may save a great deal of time and trouble later. 

6.1 PROGRAM PLANNING 

Probably the greatest pitfall awaiting the BASIC programmer is the fact that it is extremely easy to go 
to the machine and start typing in the program directly. For any but the simplest programs however 
this is fatal, and almost guarantees that the resulting program will be badly- written. 

NEVER, NEVER, NEVER start to write a program at the machine. Get well away from the 
machine, with a paper and pencil (and a rubber) and THINK. Think about the problem. What is it you 
have to do? What are the pitfalls? How can you best approach the problem? If the problem is complex 
you will probably find it helpful to draw a flow-chart at this point, breaking down into individual steps 
the process your program is designed to carry out. When you have done this, write out your program 
on paper. It is at this stage that you should try to anticipate problems - out-of-range data entries, blank 
returns, wrong data types, negative numbers instead of positive, and so on. 

6.2 BLOCK STRUCTURE 

So far as possible break up the program into separate blocks, each of which is complete in itself. 
Minimise the number of GOTO statements. Make sure that there is only one point of entry to each 
block, and only one exit. This helps to clarify the operation of the program and makes it easier to 
modify, should this subsequently be necessary. It also reduces the likelihood that your program will 
behave in unexpected ways. 

6.3 MAKING YOUR PROGRAMS INTELLIGIBLE 

Make your program INTELLIGIBLE, both for yourself and others. You will be surprised at the way 
in which you forget the working even of the simplest programs after a few weeks or months. Don't be 
afraid of REM statements. Comment your program fully - some programmers write the comments 
first, to act as a skeleton around which the flesh of the program can be built. 

Don't forget to give every program a title - one listing looks very much like another after a few 
months in your desk drawer. If the program is to be used by others, put your name on it, so that they 
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know where to come for information and advice (or with complaints!). In particular, include in the 
title of the program a version number, or, at the very least, the date, so that you can tell subsequently 
which is the most up-to-date version of the many listings you will undoubtedly accumulate. 

An introduction to explain the purpose and functioning of the program is often helpful. In the 
case of a large program, this introduction may usefully contain a table of variable names, explaining 
their significance, as well as definitions of functions, and DIM statements. In general, any item of 
program-wide significance should be placed at the head or at the end of the program. 

Lay out your program as clearly as possible. Leave spaces between words, and in general put each 
statement on a separate line, except where several short statements form a well-defined group - for 
instance, a simple delay routine. 

Use blank REM lines to separate blocks of programs. (A similar effect can be obtained by using a 
colon instead of REM.) If you're really fussy, make sure that all your line numbers are the same 
length, as this looks much prettier. 

Subroutines should be gathered together at the end of the program, and given high, memorable line 
numbers. Label your subroutines, and separate them by blank REM statements. Don't forget to put 
an END statement before your subroutines. 

Basic variable names are unhelpful, being effectively limited to two characters. PET variable 
names up to sixteen characters in length are allowed, but this is, in fact, a dangerous snare. The PET 
examines only the first two letters of the name, so that apparently distinct variable names such as, for 
instance, "DEPTH" and "DECAYTIME", would not be distinguished by the PET. It is therefore 
probably safer to stick to two-character variable names. So far as possible these should suggest the 
quantity represented by the variable - e.g. DE for delay, Tl and T2 for initial and final values of time, 
and so on. 

6.4 TESTING 

When you have written and entered your program, TEST and validate it thoroughly. Wherever 
possible, the program should be tested in sections; the tested blocks can then be linked into larger 
groupings which are tested in their turn, and so on. It is often helpful to build in small testing and 
debugging routines, which print out the values of variables at intermediate stages in the execution of 
the program. These can be removed when testing is complete. Alternatively, especially in a large 
program, it may be convenient to leave them permanently in place, "switching" them off or on as 
required by means of a software flag. When you are satisfied that you have tested the program 
thoroughly, get someone else to test it - he will certainly find some bugs that you have missed. 

Finally, if a program is large and complex, REM statements may not be adequate to explain its 
workings, so that additional documentation is required. Write such documentation immediately the 
program is complete; if you delay, it is possible that the documentation will never be written and, even 
if it is eventually written, you will have forgotten many important points. 



CHAPTER 7 

Using PET/CBM Peripherals 
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Using PET/CBM Peripherals 
- Logical Files 



PET/CBM PERIPHERALS 

By "peripherals" we normally mean devices such as the printer, disk drive unit, or even the cassette 
recorder, which are external to the computer itself. In the PET system, however, even such basic 
input/output devices as the screen and keyboard can also, if desired, be handled in the same manner as 
these external devices. We shall see in Chapter 12 that this facility can be used to good advantage. 
However, to simplify things in normal operation, the designers of the PET have provided additional 
routines to make the use of the screen and keyboard, and the loading and saving of programs on the 
cassette, less complicated. 

7.1 Logical files 

Except in a few cases such as the screen, keyboard and, to some extent, the cassette, the programmer 
must communicate with each peripheral by means of a "logical file". This technique has a number of 
advantages, and is widely used in many different computer systems of all sizes, but unfortunately it is 
rather difficult to grasp when first encountered. 

Information (programs or data) is stored by the PET on tape or disk in the form of files. The 
principle is just the same as that of the familiar office file, and a number of commands are available in 
PET BASIC to permit information to be written into or read from such "logical files". These 
commands are also pressed into use to allow data to be written to or read from peripherals, which are 
in consequence treated for programming purposes exactly as if they were logical files containing 
stored information. 

Several logical files may be in use simultaneously (up to ten at a time in the PET), and each is 
therefore labelled with a number so that they can be distinguished. This "logical file number" can 
have any value from 1 to 255, and can be selected at will within this range by the programmer. 
However, we shall see from the practical examples that it is usual to stick to low numbers and, where a 
peripheral is concerned, to select numbers related to the characteristics of the specific device 
addressed, as this makes it easier for the programmer to keep track of what is happening. 

The instruction by which we open a file to a peripheral contains information about that 
peripheral, so that once we have opened a file within a program, we can thereafter address the 
particular peripheral concerned by means of the appropriate logical file number, until the file is closed 
again (normally at the end of the program). 

When dealing with a peripheral, the information contained in the statement which opens a logical 
file consists essentially of two items, although we shall see in later chapters that where the logical file is 
a data storage file, the opening command can in some cases contain quite a lot of additional 
information. These two basic items are termed "addresses" - the "primary address" or "device 
number" and the "secondary address". 

7.2 PRIMARY ADDRESS - DEVICE NUMBER 

Most PET peripherals are electrically connected to the PET itself by a system termed the "IEEE-488 
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bus". (The "IEEE" indicates that the system conforms to a standard set by the American Institution 
of Electrical and Electronic Engineers.) 

This system is rather like the ring-main used in wiring a house -all the peripherals are connected 
in parallel to the same communicating wires, just as the domestic TV, washing machine, iron, etc are 
all connected in parallel to the house wiring. In the house, we turn on any specific item of equipment 
by operating a switch; in our computer system we obtain the same effect by sending out a signal - the 
primary address - which tells the peripherals which of them is being addressed. We may compare this 
with a school-teacher addressing a class. If she simply says "stand up" or "come here", the class will 
not know to which of them the instruction is addressed. However, if she says, for instance, "Clarence 
Cholmondeley, come here", there is no problem. In the PET system, the primary addresses are just 
numbers. Thus, the primary address of the PET printer is 4, that of the disk drive unit is 8, and so on. 
These numbers are set during manufacture, but can, if necessary, be changed, so that we can use more 
than one printer or disk drive unit on the same system. 

The standard primary addresses or device numbers in the PET system are: 

keyboard. 

1 console cassette unit where fitted, or the external cassette unit (rear or side port) if the PET is 
one of those models not fitted with a console cassette unit. 

2 second cassette unit - if a console cassette is fitted a second cassette unit can be plugged into 
the rear port. In machines with no console cassette unit, the second cassette unit can be 
connected to an additional port. 

3 screen. 

4 printer. 

8 disk drive unit. 

Other numbers up to 30 may be used for additional peripherals connected to the IEEE bus. This 
is particularly useful in technical applications where instruments such as digital voltmeters, electronic 
thermometers, etc., may be controlled by the PET and feed information back to it via the bus. 

If no primary address is specified by the programmer, the PET assumes a "default value" of 1 so 
that if the primary address of the peripheral is not given, the PET automatically assumes that the 
cassette drive is required. 



7.3 SECONDARY ADDRESS 

This is not always needed. The secondary address is essentially an instruction to the peripheral 
specified by the primary address. Some peripherals such as the PET printer, or the disk drive unit, are 
"intelligent" - i.e. they contain a microprocessor, and are capable of carrying out quite complicated 
operations without detailed instructions from the PET. The secondary address simply tells the 
peripheral which item from its repertoire is required. This facility is dealt with at greater length in the 
chapters dealing with the printer and disk drive unit - Chapters 8 and 9. 

Where a secondary address is required, but the user fails to specify a value, the PET will normally 
assume a default value of zero. The precise significance of a specific secondary address number will 
depend on the peripheral which is being addressed. 



7.4 OPENING AND CLOSING A LOGICAL FILE 

Now that we have established what the logical file must contain, we can go ahead and actually open a 
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file in the PET. This done by means of the OPEN command. Where peripherals are concerned this has 
the basic form 

OPENlfn,pa,sa 

where lfn is the logical file number, with a value in the range 1-255 

pa is the primary address, with a value in the range 1-30 

sa is the secondary address, with a value in the range 2-14 

The command 

OPEN2,4 

will thus open a channel to the printer; this channel can then subsequently be referred to by the logical 
file number - in this case 2. The (assumed) secondary address is 0. 

Since there is a limit to the number of files which can be open simultaneously, we must CLOSE 
the file when it is no longer required, and certainly before the program ENDs. The CLOSE command 
is very simple. It has the form 

CLOSElfn 

Thus the logical file OPENed above would be CLOSEd by the command 

CLOSE2 

Both these commands can be used either within a program or in direct mode. 

If by mistake a second attempt is made to OPEN a file which has not been closed in this way, an 
error message - ? FILE OPEN ERROR - will be displayed, and the file will automatically be 
CLOSED by the PET. The file must then, rather confusingly, be OPENed once again before it can be 
used. 

7.5 SENDING INFORMATION TO A PERIPHERAL - PRINT# 

Once we have opened a channel to a specific peripheral, we subsequently address that peripheral by 
means of the logical file number. We send information to a peripheral by means of the PRINT# 
command. 

Thus the sequence 

OPEN2,4 

PRINT#2, "HELLO" 
CLOSE2 

would cause a channel (lfn = 2) to be opened to the printer, the word "HELLO" to be printed, and the 
channel closed. (No secondary address is used, since the special facilities of the intelligent printer are 
not required.) 

The PRINT# command is used whenever information is to be sent to any peripheral connected 
to the IEEE bus, whether this be the printer, the disk drive unit, or some other device such as a digital 
voltmeter, electronic thermometer or counter/timer. 

NOTE that the PRINT# command must be typed out in full, and that no spaces must be left 
between the characters. PRINT# must not be input using the "?" symbol - this will give an apparently 
correct program listing, but will not work. 

7.6 GETTING INFORMATION FROM A PERIPHERAL - INPUT# AND GET# 

Once a logical file has been opened, we can request information from the peripheral using either the 
INPUT# or the GET# command. The GET# command inputs a single character from the 
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peripheral, just as the familiar GET command accepts a single character from the keyboard. The 
GET# command is rather specialised in its applications however, and is likely to be used only by the 
more expert programmer. 

The INPUT# command also functions in a very similar way to the familiar INPUT statement, 
reading a string or the value of a variable from the peripheral. Several strings or values may be input 
using a single INPUT# command. 

Thus, for instance, if we have opened a communication channel with the disk drive, using the 
logical file number 2, say, we can read in items of data from the disk very simply. 

INPUT#2,N 
will cause a number to be read from the disk and assigned as the value of the variable N. 

INPUT#2,A$ 

will cause a string to be read from disk, and assigned to the string variable A$. 

Several values may be read in at once, and these may be a mixture of strings and numerical 
variables. 

For example, the command 

INPUT#2,N$ ,N,A$ ,B$ ,C 

is perfectly valid. 

7.7 SUMMARY 

We have seen that in general the PET communicates with its peripherals by means of logical files. The 
statement which opens a file contains a primary address or device number and (optionally) a secondary 
address which in the case of an intelligent peripheral invokes some specific specialised function. 
Different logical files are distinguished by labelling them with separate logical file numbers. 

A logical file must be OPENed before use and CLOSEd before leaving the program. Information 
is sent to peripherals using the PRINT# statement, and read from peripherals by means of the 
INPUT# or (less commonly) the GET# statement. 

Chapters 8 and 9 contain many examples of the use of logical files to communicate with the 
printer and disk drive, and even with the keyboard. A logical file must also be used when data, as 
distinct from program material, is to be stored on or read from cassette. 
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The PET/CBM Printer 



INTRODUCTION 

The PET printer is "intelligent" - that is, unlike most other microcomputer printers, it contains a 
separate microprocessor of its own. This makes possible a number of very useful features not available 
on most printers. Of course, to make use of these extra facilities involves some added complexity in 
your programs but, once mastered, such features as the ability to control the print format and line 
spacing, or to advance the printer to a new page, all under program control, will be found invaluable. 
The formatting facility is especially useful in commercial and technical applications. 

8.1 THE PRINTER AND LOGICAL FILES 

Like all those PET peripherals which use the IEEE-488 bus, the printer is handled as if it were a 
logical file (see Chapter 7). Thus, once a logical file has been OPENed which corresponds to the 
printer, the PET sends text and instructions to the printer by means of PRINT# commands, just as it 
would do to a data file (see Chapters 7, 10 and 11.) 

With the printer the most basic form of the OPEN command is used. This basic format is simply 

OPENlfn,pa,sa 

lfn is the logical file number, which as usual may be selected at will in the range 1-255. 

pa is the primary address or device number of the printer. For the printer this is set during 
manufacture to 4, although it may be altered by an engineer. This may be necessary for example if two 
printers are to be used in conjunction with a single machine (other CBM primary addresses are listed 
in section 7.2). 

In the OPEN statement, sa is the secondary address which may have any value from to 7 for 
2000- and 3000- series printers, or to 10 for other models. Where no secondary address is specified, 
the "default value" - i.e. the value assumed by the PET- is 0. This causes all text to be printed just as 
received, without using any of the special facilities of the PET printer. The use of the secondary 
address is dealt with in the later parts of this chapter. 

As always, it is convenient to choose a logical file number which is the same as the primary or 
secondary address, so that it is more readily identified where it occurs in the body of a program. 

8.2 THE PRINT# COMMAND 

Once a logical file corresponding to the printer has been opened within the PET, text or data may be 
output to the printer using the command 

PRINT#lfn,data 
(Remember that the file must be closed before leaving the program.) 
For example, the sequence 

OPEN 1,4 

PRINT#1, "HELLO" 

CLOSE 1 
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will cause a logical file (number 1) corresponding to the printer to be opened, the text string HELLO 
to be printed and the file to be closed. The command PRINT#lfn opens the physical connection to the 
printer and then closes it when the requisite text has been transmitted. 

The logical file number specified in any PRINT# command must of course be that of a file which 
has already been OPENed. 

N.B. PRINT# must be typed in full; the abbreviation ?#is not permissible, and no spaces must 
be left between the characters of the command. 

Similarly, the sequence 

OPEN 1,4 

PRINT#1, X 

PRINT#1,A$ 

CLOSE 1 

will cause the current values of the variable X and the string variable A$ to be printed. 

These features may be seen from the following simple demonstration program. 

10 REM PRINTING STRINGS AND VARIABLES 

20 REM 

30 PRINT "WHAT IS YOUR NAME":INPUT N$ 

40 PRINT "HOW OLD ARE YOU": INPUT A 

50 OPEN4,4:REM OPEN LOGICAL FILE CORRESPONDING TO PRINTER 

60 PRINT#4,N$" IS "A 

70 CLOSE4 

80 END 

After OPENing a file to the printer (line 50), line 60 causes the current value of the string 
variable N$, the string " IS " and the current value of A to be printed, so: 

JOHN SMITH IS 86 

8.3 THE CMD COMMAND 

The CMD command takes the form 

CMDlfn 

and effectively transfers control from the computer to the printer. Again, the logical file number must 
be the same as in the appropriate OPEN statement. 

Subsequent output is then directed to the printer rather than to the screen. 

This is useful where a program or a disk directory is to be LISTed; text or data may also be printed 
using the simple PRINT or ? command normally used to output text or data to the screen. Since 
control is now in the hands of the printer, the communication channel between computer and printer 
remains open, even if the corresponding logical file in the computer is closed. The CMD command must 
therefore be followed by a PRINT# statement to break the communication link (i.e. to "unlisten" the 
printer) before the file is closed. The CMD command thus allows several peripherals to use the bus 
simultaneously. (As, for example, when listing a disk directory; both the disk drive unit and the printer 
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must be able to communicate with the computer during this process, unless the directory has 
previously been loaded into memory.) 

Thus, we might write 

10 OPEN4,4 

20 PRINT#4, "DEMONSTRATION" 

30 CLOSE4 
This would cause the single word "DEMONSTRATION" to be printed. 
Alternatively, we might use the sequence 

10 OPEN 17,4 

20 CMD 17 

30 PRINT "DEMONSTRATION" 

40 PRINT#17 

50 CLOSE 17 

If a faulty instruction is input - e.g. if we attempt to open a file which has already been opened - 
the computer automatically closes all the logical files which are open at that time. It does not, 
however, "unlisten" the peripherals, so that the files should be re-opened and a PRINT# command 
given for each file before closing them again. 

8.4 LISTING A PROGRAM 

To obtain a printed listing of a BASIC program present in machine memory the following instruction 
sequence may be used: 

OPEN 2,4 

CMD 2 

LIST 

PRINT#2 

CLOSE 2 

If the LIST instruction is used within a program, it automatically terminates the program; it must 
therefore be the last statement of the program. The commands 

PRINT#lfn 

and 

CLOSElfn 

should therefore be input from the keyboard after the termination of the program. 

Try using the above commands, first inputting them in direct mode from the keyboard and then 
incorporating them within simple programs. When using direct mode, it is more convenient to type the 
first three commands on a single line: 

OPEN2,4:CMD2:LIST 

A similar instruction sequence may be used to print a disk directory - this is especially simple 
when UNIVERSAL WEDGE or DOS SUPPORT is used. 
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8.5 UPPER AND LOWER CASE 

Although the printer normally operates in upper case, it may be switched from upper to lower case, 
and vice versa; furthermore, both upper and lower case may be used on the same line. 

The case may be controlled by means of the "cursor up" and "cursor down" controls on the 
keyboard. For convenience these signals will be represented here by <CU> and <CD>. If the 
"cursor down" signal is transmitted as part of a string (i.e. a piece of text), then all the remaining 
characters on the same line subsequent to the <CD> will be printed in lower case; the graphics 
characters will however be unavailable. If a <CU> is sent later in the same line, subsequent 
characters will be printed in upper case (and the graphics characters will again be available). In any 
case, as soon as an instruction to the printer is terminated by transmitting a line feed (RETURN), the 
printer will automatically revert to operation in upper case. The sequence 

OPEN4, 4 

PRINT#4, "<CD>LOWER CASE" 

CLOSE4 
will thus cause to be printed the following: 

lower case 
The sequence 

OPEN3,4 

PRINT#3,"<CD>LOWER CASE<CU>UPPER CASE" 

CLOSE3 
will produce 

lower case UPPER CASE 

8.6 CHARACTER CODES - THE CHR$ FUNCTION 

All characters are transmitted from the computer to the peripherals as numbers. We may thus replace 
"<CU>" and "<CD>" by the equivalent numerical codes - CHR$(145) and CHRS(17) respec- 
tively. 

The above sequences would then become 

OPEN4,4 

PRINT#4,CHR$(17)"LOWER CASE" 

CLOSE4 

and 

OPEN3,4 

PRINT#3, CHR$(17)"LOWER CASE"CHR$(145)"UPPER CASE" 

CLOSE3 

8. 6. 1 Other uses of the C HR$ function 

This method of transmitting characters to the printer is not essential where the <CU> and <CD> 
signals are concerned, but some other characters must be sent in this form. 
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For example, if inverted commas are to be printed out within a string of text, they cannot be sent 
in the normal way - e.g. "SAY "HELLO" " - since the second quotation mark will be taken to 
indicate the end of the string. In this case the inner quotation marks must be input as the appropriate 
ASCII code - CHR$(34): 

OPEN200,4 

PRINT#200, "SAY" CHR$(34)"HELLO" CHR$(34) 

CLOSE200 

Similarly, when using disk drives, it may sometimes be necessary to transmit in this form 
characters commonly used as terminators - the colon, RETURN, etc. 

NB Where some CHR$ expression is to be used repeatedly within a program, it may be 
preferable to define a string variable with the appropriate value. For example, the last instruction 
sequence would then become: 

OPEN200,4 

C$ = CHR$(34) 

PRINT#200, "SAY"C$"HELLO"C$ 

CLOSE200 



8.7 MORE ADVANCED APPLICATIONS OF THE CBM PRINTER 

8.7.1 Enhanced characters 

The PET printer is a "matrix" printer; each character is formed by an array or matrix of separate dots. 
Each character is built up in this way within a rectangular grid. The grid has 6 vertical lines of dots and 
seven horizontal rows, so that a completely black rectangle (such as a reverse-contrast space) will be 
represented by a complete matrix of 42 individual dots. 

Any character may, for emphasis, be printed twice its normal width; each column of the 7-row 
6-column matrix is then repeated, so that an 'enhanced' character occupies a 7-row 1 2-column matrix. 



Normal Enhanced 

This is achieved by sending the control signal CHR$(1) in front of the character or characters to 
be enhanced. The character format is returned to normal by the control signal CHR$(129). These 
characters have no equivalent on the keyboard and so must be sent in this manner. The format is 
automatically returned to normal when an instruction to the printer is terminated by the transmission 
of a line feed (RETURN). Thus, if a number of lines are to be printed in enhanced characters, the 
character CHR$(1) must be sent at the start of every line. 

Enhanced characters are useful in headings, or to emphasise selected words or letters. 
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For example: 

OPENl,4 

PRINT#1, CHR$(l)"H"CHR$(129)"ELLO" 
CLOSE 1 
will cause the word "HELLO" to be printed, with the first letter H enhanced. 

8.7.2 Multiple enhancement 

A character may be enhanced more than once, so as to occupy a matrix 18, 24, 30, or even more 
columns in width; for example, the instruction sequence. 

OPEN4,4 

PRINT#4, "S"CHR$(1)"A"CHR$(1)"L"CHR$(1)"F"CHR$(1)"0"CHR$(1)"R"CHR$(1)"D" 

CLOSE4 

will cause each successive letter to be enhanced by an additional 6 columns. 

8.7.3 Paging 

Normally, the printer prints continuously, putting 66 lines of text on each standard 1 1-inch page. It is, 
however, possible to make the printer operate in a "paging" mode. 

When this option is selected, the printer prints 60 lines of text per standard page, with three blank 
lines at the top and three at the bottom of each page (assuming of course that the paper is initially 
correctly set). 

Once the printer has been set to the paging mode it will continue to operate in this mode until 
either paging is turned off again, or the machine itself is switched off. 

"Paging" is turned on by transmitting the character CHR$(147) and turned off by transmitting 
CHR$(19). CHR$(19) represents the character generated by pressing the HOME key of the 
keyboard while CHR$(147) represents CLR, generated by pressing SHIFT and HOME simultane- 
ously. 

For example, the sequence of instructions 

OPEN4,4 

PRINT#4,CHR$(147) 

PRINT#4,data 

PRINT#4,CHR$(19) 

CLOSE4 

will turn on the paging facility, print out the data or text, and turn off paging. 

8.7.4 The head-of-form facility 

When paging is turned off in this way, the printer will advance to the head of the next page, ready to 
start printing again. The paging-off command thus offers a "head-of-form" facility, allowing text to be 
printed repetitively on successive pages, in the same position on each page. 
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The paging instruction may if preferred be transmitted as a string, using the HOME and CLR 
(shifted HOME) keys. 

PRINT#4,"<CLR>" 

and 

PRINT#4,"<HOME>" 

would thus turn paging on and off, respectively. 

The use of the head-of-form facility is demonstrated by the following simple program: 

10 OPEN4,4 

20 PRINT#4,CHR$(147) 

30 PRINT#4,TAB(12)CHR$(l)"TOP OF FIRST FORM" 

40 PRINT#4 

50 PRINT#4, "THIS PROGRAM DEMONSTRATES THE USE OF HEAD- 
OF-FORM FACILITY." 

60 PRINT#4,CHR$(19) 

70 PRINT#4,TAB(12)CHR$(l)"TOP OF NEXT FORM" 

80 CLOSE 4 

90 END 

8.7.5 Overprinting 

It is possible to overprint a line by forcing a carriage return without a line feed. This is done by 
transmitting the character CHR$(141). The facility is useful in synthesising symbols or characters - 
such as the £ sign - not present on the PET keyboard. It is also invaluable where a heading or title is to 
be underlined. 

The following short program demonstrates how a reasonable £ sign may be printed. 

10 OPEN6,4 

20 PRINT#6,CHR$(17)"F100"CHR$(141)"_" 

30 CLOSE 

The CHR$(17) sets the printer to lower case, so that 'F' in the immediately following string is 
printed as 'f . A carriage return without line feed is then carried out, and the 'f is underlined, so 
producing a recognisable £ sign: f. (The underline is produced by simultaneous depression of the 
SHIFT and $ keys.) 

8.8 THE SECONDARY ADDRESS 

All the facilities described so far have been invoked by the use of control characters, the assumed 
value of the secondary address being zero. There are, however, a number of other invaluable facilities 
which may be called into operation by means of the so far unused secondary address in the OPEN 
statement. In the case of the CBM 2022 and 3022 (tractor feed) models, seven different facilities may 
be called into play by using the appropriate secondary addresses. Most, but not all, of these facilities 
are also available on the corresponding friction-feed models. Eleven secondary addresses are avail- 
able on the 4022 printer. 
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Note that in some cases several OPEN statements in succession may be necessary, to set all the 
required options. (Up to ten files may be open simultaneously.) 

The seven available secondary addresses available on all the tractor-feed printers are: 

Print data as received. (This is the default value - i.e. the value assumed by the printer if no 
secondary address is included in the OPEN statement.) 

1 Print data according to a previously specified format. (The format is separately specified 
using an OPEN command with secondary address 2.) 

2 Accept and store formatting data 

3 Set page size (for use with "head-of-form" facility) 

4 Enable diagnostic (error) messages to be output by the printer 

5 Define a special character, of form specified by programmer 

6 Adjust spacing between lines (tractor- feed models only). 

8.8.1 Formatting - Secondary Addresses 1 and 2 

We have already seen that if no secondary address (or a secondary address of 0) is used in the OPEN 
statement, text and data will be printed exactly as they are received from the PET by the printer. This 
can be inconvenient, as it may be difficult to arrange a string precisely as required; also, unless we take 
special precautions, the value of a numerical variable will be printed using the maximum available 
number of significant figures, just as it would be on the screen. 

These difficulties can be avoided by making use of the automatic formatting facilities of the PET 
printer. This is done by sending to the printer a string which specifies the desired format. This is stored 
in the printer, and whenever formatted output is specified by the program, the data sent are printed 
exactly according to the specified format. 

NOTE however that there are a number of 'bugs' in the PET printer firmware . If something goes 
wrong when you use the more advanced facilities, do not automatically assume that it is your fault. 
These bugs are particularly irksome in the case of the formatting facility. Do not be put off by them - 
the facility is so useful that it is worth persevering. 

8.8.2 Specifying the format 

The format is sent to the printer as a single string, using dummy symbols for letters and numbers. This 
format string is sent via a logical file with a secondary address of 2. Subsequently, text and data will be 
printed according to the specified format if they are sent to the printer by means of a logical file with a 
secondary address of 1 . 

We can mix string variables (i.e. alphanumeric symbols) and numerical variables on the same 
line. However, the formats for the two types of variable are differently specified. 

Alpha-numeric Strings 

The dummy character used within the format statement is "A"; blanks are indicated simply by blanks, 
so: 

AAAAA AA AAAAAAA 

Each string variable sent within a single print statement is allocated to the next group of A's in the 
format statement in turn, one character being printed for each "A". Excess characters, and leading 
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blanks, are discarded. Thus, the following instruction sequences (which could be input in either direct 
or program mode) would produce varying results according to the length of the string variable Z$. 

10 OPEN 1,4,1 

20 OPEN 2,4,2 

30 PRINT#2, "AAAAA" 

40 PRINT#1,Z$ 

50 CLOSE l:CLOSE2 

60 END 

If the string represented by Z$ has five letters, it will fit exactly into the specified format; if more 
than five, it will be shortened to fit. Thus, if we run the program with Z$ equal in turn to, say, 
"PETER", "MARMADUKE" and "TOM", we shall get 

PETER 

MARMA 

TOM 

We can format several string variables on the same line, but in this case we must follow every 
string, apart from the last, with the "skip" character CHR$(29), to indicate the end of that string. 
Ordinary delimiters such as the colon, full stop, comma, etc will be treated as part of the string; only 
the special skip character will be recognised. The skip character is not necessary after numerical 
variables, however. The skip character CHR$(29) is the signal produced by pressing the CURSOR 
RIGHT (->) key on the keyboard, so that it may be sent either as CHR$(29) or as "-»". 

If one string is to consist solely of blanks, this too must be indicated by a special character. 
Otherwise, as we have already seen, leading blanks are ignored, and the printer will therefore ignore 
the whole of the blank string. The null string character is CHR$(160). 

The following short program demonstrates these features. 

10 OPEN 1,4,1 

20 OPEN 2,4,2 

30 PRINT#2," AAAAA . . AAA AAAAAA . „ AAAAAAA" 

40 Z$ = "COMPUTER":Y$="CALCULATOR" 

50 PRINT#1, Z$CHR$(29)Y$CHR$(29)CHR$(160)CHR$(29)Z$ 

60 CLOSE l:CLOSE2 

70 END 
This will produce the following print-out: 

COMPU CAL COMPUTE 

The effect of the null string may clearly be seen. This process is fairly complicated and some 
experimentation may be necessary before a program produces the desired results. 

Numerical variables 

The dummy character used in the case of numerical variables may be either Z or 9; the two produce 
quite different results. The decimal point, if any, is indicated in the usual way. 
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Where 9 is used as the dummy digit, leading zeros (before the decimal point) are suppressed and 
replaced by blanks. If Z is used (and this is allowed only before the decimal point) leading zeros are 
printed, and indeed inserted if necessary to fill out the format. 

Possible formats thus include, for example, 

99.999 ZZZ.99 ZZ 99 

Consider the two similar formats ZZZ.99 and 999.99. If now the number .123 is printed using 
these two formats in turn, the results will be respectively: 

000.12 and .12. 

In each case, extra trailing digits are ignored. 

Serious errors could result in the case of numbers too large to fit within the specified format; to 
avoid confusion in such a case, the digits are not printed at all, but replaced by asterisks (*). Thus, if we 
try to print, for instance, 12345.67, using the format 999.99, the print-out will be 

Thus we can see at a glance whenever such an overflow has occurred. 

Sign 

The sign of a number will not be printed unless this is specified in the format statement. There are two 
possible forms. If the letter ^precedes the string then the sign, whether + or-, will always be printed in 
the specified column position. If however the format string is terminated by a - sign, then a positive 
number will be followed by a blank and a negative number by a minus sign. 

As with strings, several numbers may be printed on the same line. For example: 

10 OPENl,4,l:OPEN2,4,2 

20 PRINT#2,"SZZZ.99 SZZZ ZZ.99- 999" 

30 X=-123.456: Y=6.789 

40 PRINT#1,X,X,X,X 

50 PRINT#1,Y,Y,Y,Y 

60 CLOSEl:CLOSE2 

70 END 

The print-out from this program will help to make the effects of the various format options more 
clear. 

Mixed Strings 

In general, we will need to mix both numerical variables and strings on the same line. This is readily 
done by means of a combination of the various dummy symbols discussed. However, care must be 
taken to insert all the necessary skip characters if the formatting is to be successful. 

At this stage two bugs should be noted. 

1 When a formatted message has been printed, an attempt to send a second format string to the 
printer immediately will lead to unexpected and unwanted results. This problem may be 
avoided by printing an unformatted message before attempting to input a new format. A 
blank line, or even a carriage return without line feed [CHR$(141)] will do. The need for this 
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may be confirmed by removing line 280 in the demonstration program below, and running 
the program several times in succession. 

2 Occasionally it may be impossible to obtain satisfactory results with some particular format. 
In this case it will usually be found that simply re-arranging the order of the variables in the 
format string will produce satisfactory results. 

Example 8.1 

The following demonstration program gives some idea of the use of this facility. It produces a 
formatted print-out in the form of an imitation stock-list, as shown below the listing. Lines 130, 280 
and 310 are present solely to avoid the first of the two bugs just described. The skip character is 
allocated a string variable name - C$ - for convenience. The strings "ITEM" and "WIDGETS, 
PURPLE, TYPE" are also allocated to string variables. This will generally be found convenient since 
it simplifies any changes in the text which may subsequently be required. It is convenient also to 
transmit the format string itself as a variable; among other things, this has the advantage that a longer 
format string can be used than when this is input directly as part of the PRINT# statement. If you 
really want to use every one of the printer's 80 characters per line, it will be necessary to build up the 
string using two separate string variables, since otherwise it is impossible to input an 80-character 
string. 

100 REM MIXED FORMAT STRINGS 

110 REM ***** ****** ******* 

120 REM 

130 0PEH4..4 

140 OPEN 1,4,1 

150 0PEN2,4,2 

lfifl F*="fiAAA 99 AAAAAAAAAAAAAAAAAfiA ZZ 999y" 

170 REM TRANSMIT FORMAT STRING 

ISO PRINT#2,F* 

1 90 A*= " W I DGETS , PURPLE , TVPE " 

280 B*="ITEM" 

210 B=56 

220 C*=CHR*<29) 

230 FOR 1=1 TO 5 

240 A= I NT ■:: RND < 1 > * 1 88 > 

250 C=28+I 



260 PRINT#1, 


B*,C$, I, A* 


270 NEXT I 




280 PRINT#4 




290 CLOSE 1 




300 CL0SE2 




310 CL0SE4 




320 END 




ITEM 1 


WIDGETS 


ITEM 2 


WIDGETS 


ITEM 3 


WIDGETS 


ITEM 4 


WIDGETS 


ITEM 5 


WIDGETS 



PURPLE, TVPE 21 71 

PURPLE, TVPE 22 85 

PURPLE, TVPE 23 15 

■PURPLE, TVPE 24 67 

■PURPLE, TVPE 25 22 



8.8.3 Setting the number of lines per page - secondary address 3 

This option is used in conjunction with the head-of-form facility where paper with pages of length 
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other than the standard eleven inches is being used, or where it is desired to print text repetitively at 
fixed intervals, several times per page. (Tractor feed models only). 

The instruction sequence necessary to change the page length differs slightly for the 3000- and 
4000-series printers. With a 3022 printer the sequence would be of the form 

OPEN6,4,3 

PRINT#6,15 

CLOSE6 

With a 4022 printer, however, the second command would be 

PRINT#6,CHR$(15) 

The number transmitted in the PRINT# statement determines the effective page length. Some 
experiment may be required before the desired page length is obtained. Once the page length has 
been set to a non-standard value in this way, it will remain at the new value until reset, or until the 
printer is turned off. 

8.8.4 Error messages - secondary address 4 

The printer can issue a number of simple diagnostic error messages. If these are required, a file with a 
secondary address of 4 must be opened (and later closed, of course). 

For example: 

OPEN4,4,4:REM ENABLE ERROR MESSAGES 



(body of program) 



CLOSE4 

8.8.5 Special characters - secondary address 5 

The user can define any character which can be accommodated in the standard 7x6 matrix. The 
characters are specified by means of a series of decimal numbers each specifying the contents of a 
column in the matrix. Each row of the matrix is allocated a "weight" as shown below. Consider as an 
example the Greek character "X". 



64 

32 
16 

8 
4 
2 
1 



X 


X 


X 


X 


X 


X 




X 














X 














X 










X 










X 










X 


X 


X 


X 


X 


X 



65 99 85 73 65 65 
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Looking at the left-hand column, we see that the squares corresponding to 1 and 64 are occupied. 
The number representing this column is therefore 1 + 64 = 65 . In the second column, squares 1,2,32 
and 64 are occupied so that the number for this column is 1 + 2 + 32 + 64 = 99. The remaining four 
numbers are calculated in the same way. 

The character can then be sent to the printer using secondary address 5 

OPEN5,4,5 

C$ = CHR$(65) + CHR$(99) + CHR$(85) + CHR$(73)+CHR$(65)+CHR$65) 

PRINT#5,C$ 

CLOSE5 
Once this has been done, the character may then be printed; it is represented by CHR$(254). 

OPEN4,4 

PRINT#4, CHR$(254) 

CLOSE4 

The method shown above is very cumbersome, and makes it difficult to alter the stored special 
character; it is more convenient to input the character by means of a DATA statement. For example: 

100 DATA65,99,85,73,65,65 

200 OPEN5,4,5 

300 FOR 1=1 TO 6 

400 READ C 

500 C$ = C$ + CHR$(C) 

600 NEXT I 

700 PRINT#5,C$ 

800 OPEN4,4 

900 PRINT#4,CHR$(254)"(X*Y+Z)" 

1000 CLOSE4 

1100 CLOSE5 

1200 END 

A number of different special characters may be used, each being selected simply by changing the 
data in the DATA statement. Try your hand at generating other symbols - for example a £ symbol, or 

a face. 

Some difficulties may arise if attempts are made to print a special character continuously, but 
where the special character is used only as part of printed text, no problems should be encountered. As 
usual with the PET printer, this is due to the bug which crops up whenever two PRINT# statements to 
logical files with secondary addresses are carried out in succession. As usual also, this may be avoided 
by interpolating a PRINT# statement to a logical file without a secondary address between the two 
offending instructions. 
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8.8.6 Line separation - secondary address 6 (tractor feed models only) 

In the tractor-feed printers, the paper is advanced in a series of small steps - 144 steps/inch for the 
2022 and 3022 printers, and 192 steps/inch for the 4022. 

The number of steps between successive lines of printing can be set by means of a logical file with 
a secondary address of 6. 

Where the line separation is not specifically set in this way, the printer will print at a default value 
of 6 lines/inch - i.e., 24 steps/line on a 2022 or 3022, and 36 steps/line on a 4022. 

Once set, the spacing remains at the new value until either it is reset or until the printer is switched 
off. 

It is therefore good practice to reset the spacing to the standard value at the end of your program. 
Where the printer is often used with non-standard line spacings, it may in any case be worthwhile to 
reset the spacing to the standard value at the beginning of every program, just in case the spacing is 
already set to some other value. The sequence of commands required to set the line spacing is: 

OPEN6,4,6 

PRINT#6,CHR$(48) 

CLOSE6 

The value of 48 used here will reset the line spacing to 48 steps/line - i.e., 3 lines/inch on a 2022 or 
3022, and 4 lines/inch on a 4022 printer. Clearly other values may be used at will. The sequence of 
commands may be input either as part of a program or direct from the keyboard. 

Note however that as in the case of the formatting facility, difficulties arise where successive 
PRINT# statements with secondary addresses follow immediately upon one another. To avoid this, 
some other PRINT# statement must be directed to the printer between instructions to alter the line 
spacing. This precaution is particularly important where the spacing is reset at the beginning and end 
of the program, since otherwise problems may be encountered if the program is run repeatedly. 

Where programs involve a large number of PET graphics symbols, it may be useful to print the 
listing at 8 lines/inch, rather than the standard 6. This eliminates the gaps between the symbols on 
successive lines. The adjustment to the line spacing is readily carried out from the keyboard before 
printing the listing. 

Note that some difficulties may arise if the paging facility is used with a non-standard line- 
spacing; the effective page length may need to be reset if paging is to operate correctly. 



8.9 ADDITIONAL FEATURES OF THE 4022 PRINTER 

The facilities discussed so far are available on the 2000-, 3000- and 4000-series printers alike. 
However, the 4022 printer also has some additional facilities, invoked by using the secondary 
addresses 7-10, which are not available on the earlier machines. 

8.9.1 Lower Case/Upper Case - secondary address 7 

The printer normally prints in upper case (capital) letters: where a shifted character is encountered, 
the corresponding graphics symbol is printed, just as on the PET screen. 

However, we already know that the character set of the screen display can be changed, by means 
of the instruction POKE 59468,14. In 2000-, 3000-, and 4000-series PET's, this instruction causes 
unshifted characters to be printed on the screen in lower case and shifted characters in upper case, just 
as with a conventional typewriter. 
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The 4022 printer can similarly be switched to an alternative character set, by using a secondary 
address of 7. For example, the instruction sequence 

OPEN7,4,7:PRINT#7:CLOSE7 

will cause the printer to reproduce unshifted characters in lower case, and shifted characters as 
upper-case letters and numerals, rather than the corresponding graphics symbols. It is clearly 
desirable that the printer and PET should operate in the same manner, so that the complete sequence 
of instructions would normally be: 

POKE 59468,14:OPEN7,4,7:PRINT#7:CLOSE7 

8.9.2 Upper case/graphics - secondary address 8 

The PET can be returned to its normal mode, printing only upper-case characters and graphics 
symbols, by means of the instruction POKE 59468,12. (2000-, 3000- and 4000-series machines). 

Similarly the printer can be reset to the upper case/graphics mode by writing to a secondary 
address of 8. Again, it is desirable that both PET and printer should be operating in the same mode, so 
that an appropriate instruction sequence would be: 

POKE 59468,12:OPEN8,4,8:PRINT#8:CLOSE8 

8.9.3 Disable error Messages - secondary address 9 

If the printer error message facility has been enabled, it may be disabled by writing to a secondary 
address of 9. For instance: 

OPEN9,4,9:PRINT#9:CLOSE9 

8.9.4 Resetting the printer - secondary address 10 

If we write to a secondary address of 10, all the special functions are reset to their original state, just as 
if the printer were switched off and on again. This is a particularly useful facility, since such quantities 
as the line spacing may be conveniently reset to their standard values by a single line at the end of a 
program. 

For instance: 

OPEN10,4,10:PRINT#10:CLOSE10 

Note: In many cases, it is necessary to run a program on a variety of systems. Where this is so it 
may be better to leave these additional facilities of the 4022 printer unused, so that your 
program will be "portable" between systems using any of the 2000-, 3000- or 4000- 
series printers. 
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Disk Units 



9.1 FLOPPY DISKS 

The "floppy disk" now so widely used for bulk storage is a disk of thin flexible plastic coated with a 
magnetic material similar to that used on magnetic recording tape. Two standard sizes of disk are 
available - 8-inch and 5finch. The smaller size, the "mini-floppy" or "diskette" is almost universally 
used in microcomputer applications. The disk is sealed inside a stiff protective envelope, with 
openings through which the mechanical drive unit and the magnetic recording head of the disk drive 
can make contact with the disk. The disk never leaves the envelope; the envelope remains stationary 
while the disk revolves within it to allow the head to access points over the whole of the working 
surface. At one side of the envelope is the "write protect" notch. If this is covered the disk contents 
cannot be altered. 

Data and/or programs can thus be stored magnetically on the disk in precisely the same manner as 
on cassette tape . However, the capacity of the disk is greater - roughly that of a full C90 cassette - and 
the speed of recording and reading is between 50 and 100 times greater. The reliability of reading and 
recording is also much better than for cassettes. 

Several types of disk drive units have been produced by CBM, and a twin drive unit produced by 
Computhink is also in fairly common use. The Computhink system has been largely superseded by the 
latest CBM units which have superior disk handling facilities. The earliest CBM units, the 2040 and 
3040 were twin drive systems with a Disk Operating System called DOS 1. These systems use rather 
cumbersome operating techniques, but the more recent 4000 and 8000 series computers have disk 
control commands incorporated into BASIC 4. The 4040 disk drives operating with DOS 2 are 
identical in many respects to the 3040 drives and it is possible to upgrade the 3040 by replacing the 
ROM chips so that BASIC 4 commands can be employed. 

CBM have recently introduced a more economical single drive unit (the 2031 system) which 
operates with BASIC 4 and DOS 2. 

The use of disk drives, particularly the early units, is greatly simplified by employing a utility 
program supplied by the manufacturers. According to the version, this program is called "DOS 
SUPPORT" or "UNIVERSAL WEDGE". The operation of the program is described later in this 
section and it is well worth the time spent in learning the somewhat arbitrary syntax. 

The use of all these disk drive units is described in the following sections. 



9.2 THE DISK DIRECTORY 

Any disk drive unit contains a complex microprocessor-based control system which operates accord- 
ing to a built-in program - the disk operating system (DOS). 

One of the functions of the DOS is to keep track of the identity of the disk and of the files 
(programs or data) which it carries. To this end, a few data blocks (roughly a thousand bytes - 
equivalent to about two hundred words in English) are dedicated to storing the identifying name and 
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number of the disk, together with a list of the names and sizes of the files stored upon it, and the 
amount of space remaining. This information constitutes the disk directory, and may be examined by 
the user via the microcomputer screen. 

9.3 USING 2000 AND 3000 SERIES CBM DISK DRIVES 

a) Check that both the PET and the disk drive unit are turned OFF. 

b) Make sure that the disk drive unit is connected to the IEEE port of the PET - i.e. the 
connector nearest the centre of the machine, at the back. 

c) Switch on the PET. 

d) Open the disk drive doors and CHECK THAT THERE ARE NO DISKS IN THE DRIVE. 
The CBM drive unit must NEVER be switched on with a disk or disks in position. If this is 
done it is almost certain that any program or data stored on the disk will be corrupted. 

e) Switch on the drive, using the mains switch in the back panel of the disk drive unit. The 
LED's in the front panel should glow briefly and then go out. 

f) Insert the disk or disks and close the drive door(s). The disk must be inserted with the label 
on top and nearest the user. 

9.3.1 Loading a program from disk into PET memory 

Assuming that a disk is available on which programs have previously been saved, the following 
procedure should be followed. (The explanatory notes in each sub-section need not be read the first 
time round - the instructions may be regarded simply as a recipe.) 

a) Insert the disk in the drive. 

b) Type in the command 

OPEN15, 8, 15 

The first of the numbers in this command need not be 15 - any number up to 
255 can be used; however the same number must be used in the PRINT # 
commands used later. The other two numbers, 8 and 15, must not be changed. (See 
Chapter 7.) 

This command opens a channel of communication between the PET and the disk drive. If you 
subsequently input an incorrect command, the channel ("file") will automatically be closed, and must 
be re-opened, using the above command, before proceeding further. 

c) "Initialize" the disk by typing 

PRINT#15,"I0" 

or PRINT#15,"I1" 

according to which drive is being used. If both are to be initialized, this may be done by means of the 
command 

PRINT#15, "I" 

The INITIALIZE command aligns the drive unit with the tracks on the disks, reads the directory from 
the disk and loads the disk identification data into the DOS. This command must be used whenever a 
fresh disk is placed in the drive, or when a disk is removed and replaced. 

[For best results, open the drive doors before giving the INITIALIZE command, and close each 
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door a couple of seconds after the appropriate indicator LED lights up, showing that the drive is in 
use. This procedure helps centralise the disk.] 

d) The selected program may now be loaded using the command 

LOAD"drno:progname",8 

drno is the number (0 or 1) of the drive in use, and progname is the name of the program to be loaded - 
e.g. 

LOAD"0:MATMULT",8 

The program is now loaded into the microcomputer, any BASIC program already stored there 
being automatically erased. When loading is complete (after a few seconds) the program may be 
RUN, LISTed or modified in the usual way. Other programs may be LOADed from the same disk 
without re-initialization. 

9.3.2 The disk directory 

The disk directory may be inspected by means of the command 

LOAD"$drno",8 

When loading is complete the directory may be displayed on the screen by means of the command 
LIST. 

9.3.3 Saving a program on disk 

Where the disk has previously been used but is not full, this is quite straightforward. 

a) The disk is inserted in the drive and initialized as before, using the appropriate command 

PRINT#15,"I" 
PRINT#15,'T0" 
OR 
PRINT#15,'T1" 

b) The program is then SAVEd using the command 

SAVE"drno:progname",8 

9.3.4 Verifying a saved program 

After being SAVEd, the program may be verified. This process checks the SAVEd program against 
the original stored in the PET, to check that it has been correctly written to the disk. 

The appropriate command is: 

VERIFY"drno:progname",8 
Note that the commands LOAD, SAVE and VERIFY all have exactly the same format. 
Where a program is verified immediately after being saved, the abbreviated command 

VERIFY"*", 8 
may be used. 

It is good practice to VERIFY every program as it is SAVEd. 
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9.3.5 Using a new disk (or erasing and re-using an old disk) 

Where a disk has not previously been used or is to be completely erased and re-used, the procedure is a 
little lengthier. Before being used, the disk must be "formatted"; this process divides the disk into 
sectors, imprinting magnetic signals upon it to indicate the limits of each sector. 

To do this the disk is placed in the drive. The command OPEN 15,8,15 is given, if this file has not 
already been opened, and the disk is formatted by means of the command 

PRINT#15,"Ndrno:diskname,id" 

diskname is any name up to 16 characters long, and id is a two-character identifier; both may be 
selected at will by the user. ('N' stands for NEW). 

9.3.6 Other Commands 

It is good practice to close the link between computer and disk drive after use by means of the 
command 

CLOSElfn 

(lfn is the "file number" used in the original OPEN statement.) 

A number of other commands using the format 

PRINT#lfn," " 

are available: we have already seen the use of the INITIALIZE and NEW commands. Other 
commands which may be used when the user has developed some confidence are: 

D - DUPLICATE: duplicates an existing disk 

C - COPY: copies files, either on the same or different disk 

R - RENAME: allows the name of an existing file to be changed 

S - SCRATCH: deletes a file 

V - VALIDATE: creates a map of the available blocks on the disk, and initializes the disk. 

FOR FURTHER DETAILS ON THE USE OF THESE COMMANDS, THE CBM FLOPPY 
DISK USER MANUAL SHOULD BE CONSULTED. 

9.4 USING THE 4000 SERIES CBM DISK DRIVE 

The 4000 series of CBM computers and accessories using BASIC 4.0 (introduced late 1980) are 
provided with an additional set of DOS commands. These are incorporated in the computer ROM and 
can be regarded as an extension to the BASIC peripheral commands. 

Compatibility 

All the DOS 1 commands described in the previous section can be used with the 4000 series drive. A 
program which has been saved using a 3000 series disk drive can be loaded by means of a 4000 drive 
unit; however, 3000 series formatted disks cannot be used for saving additional programs with a 4000 
series unit. 

9.4.1 Starting up 

The starting up procedure is identical for both disk drive series. It is important never to switch the disk 
drive on with a disk in position. 
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9.4.2 Loading a program from disk into PET memory (4000 series) 

If a unique ID is assigned to each disk no initialization procedure is required with the 4000 series unit. 

The command 

DLOAD"progname",Ddrno 

will cause the program entitled "progname" to be loaded into PET memory. 

The drive number (drno) will default to if not specified: 

DLOAD"progname" 

will load the desired program from drive number 0. 

The 4000 series DOS also contains a useful quick load procedure: 

Switch the computer and the disk drive unit on and insert a disk into drive 0. Simultaneously press 
the SHIFT and RUN/STOP keys. The computer will initialize the disk in drive and load the first 
program into PET memory. 

9.4.3 The disk directory (4000 series) 

The disk directory may be inspected by means of the command 

DIRECTORYD0 or DIRECTORYD1. 
This format can be shortened to: 

DL.D0 or DLD1 
A shifted R produces the "_" in the short format. Typing 

DI_ 

will display the directory for disks in both drives. The command CATALOG (or C shifted A) can 
alternatively be used. 

During the listing of the directory, the space key can be used to stop and then restart the listing. 
This is particularly useful because a large directory, when listed, will scroll off the screen. 

9.4.4 Saving a program on disk (4000 series) 

Where a disk has previously been used but is not full, the procedure is very straightforward. Normally, 
no initialization is required. 

The command 

DSAVE"progname",Ddrno 

will save the file (progname) on drno 1 or 0, The program name may be up to 16 characters long. 

9.4.5 Verifying a saved program (4000 series) 

The format of the VERIFY command for the 4000 series is the same as that for the 3000 series. 

VERIFY"drno:progname",8 
or 

VERIFY"* ",8 
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9.4.6 Using a new disk (4000 series) 

Before being used for the first time, the disk must be "formatted". 

This is done with the aid of the HEADER command. The format is:- 

HEADER "dn",Ddrno,Iid 

where dn = disk name supplied by the user and limited to 16 characters. 

drno = drive number, 1 or 

id = the disk ID, which is a unique two character alphanumeric identifier, supplied by the user. 

9.4.7 BACKUP (4000 series) 

This command can be used to create a backup copy of a disk and has the format 

BACKUP Dsdr TO Dddr 

sdr - source drive (either or 1) 

ddr - destination drive (either or 1) 

BACKUP can only be used with disks formatted on a 4000 series machine. 

9.4.8 COPY (4000 series) 

With a formatted disk (using the HEADER command) COPY can be used to copy either the whole of 
the contents or a single program from one disk to another. 

COPY Dsdr TO Dddr 
can be used to copy the whole disk. 

COPY Dsdr, "progname" TO Dddr,"progname" 

will copy a specified program. 

again sdr is the source drive, either 1 or 0. 
again ddr is the destination drive, either 1 or 0. 

COPY can be used to copy 3040 formatted disks onto a 4040 formatted disk. 

9. 4. 9 SCRATC H ( 4000 series) 

This command is used to erase a specified program. The format is:- 

SCRATCH Ddrno,"progname" 

where drno = 1 or 0. 

Not all of the available BASIC 4.0. commands have been described in this brief introduction to 
the use of the 4000 series disk drive unit. 

Other commands are available for file and data management and these are referred to in the 
chapter relating to disk file handling procedures. 

9.5 DOING IT THE EASY WAY - USE OF THE UNIVERSAL WEDGE PROGRAM 

The reader will by now have realised that the use of the commands listed above is tiresome and 
liable to result in error. The situation may be greatly improved by means of a support program which 
extends the facilities of the disk operating system. Such a program - UNIVERSAL WEDGE - is 
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supplied on disk by CBM, and it is so suitable for the purpose that the operator should consider storing 
UNIVERSAL WEDGE as the first file on every disk. (It occupies only 6 of the available 690 data 
blocks). The program is called DOS SUPPORT on the utility disk which is supplied with earlier 
machines. 

9.5.1 Loading UNIVERSAL WEDGE 

If UNIVERSAL WEDGE, in whatever version is available, is stored as the first file on a disk, and the 
disk is inserted in drive (observing the precautions listed in section 9.1), the process of opening files, 
etc, may be avoided. Immediately after turning on the drive and inserting the disk simply type in the 
command 

LOAD"*",8 

and when loading is complete, type in the command RUN. The quick load procedure (SHIFT RUN) 
can be used with 4040 drives. 

This special LOAD command opens the file, initializes drive and loads the first file (in this case 
UNIVERSAL WEDGE) from the disk in drive 0. Once UNIVERSAL WEDGE has been LOADed 
and RUN, the format PRINT#,". . ." is no longer required. A command requiring this format will be 
obeyed if it is preceded by either of the symbols 

@ or > 

BUT note that other commands such as SAVE and VERIFY must be typed in as before, using the 
format 




"drno : progname" ,8 
or «"- — "-" 

9.5.2 Use of UNIVERSAL WEDGE 

For example, the command 

>I1 
will cause drive 1 to be initialized; the command 

@I 
will cause both drives to be initialized. 
The commands 

>$0 >$1 or >$ 

will cause respectively the directories of the disks in drive 0, drive 1, or both drives to be displayed. 

[An incidental advantage here is that when this command is used to access the directory, any 
program already in the machine is not over-written and lost, as is the case when the LOAD and LIST 
commands are used to display the directory.] 

9.5.3 Loading a program 

Under UNIVERSAL WEDGE, a program may be loaded simply by typing a slash (/) followed by the 
program name. The drive number may be specified or not, as desired: 

/progname or /drno: progname 

e.g. /CHEMSIM or /0:SPACE INVADERS 
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9.5.4 Loading and running a program 

When a program has been loaded, it can be RUN in the usual way; alternatively, if an up arrow ( f ) is 
used in place of a slash, the program will be loaded, and then automatically RUN as soon as loading is 
complete. For example 

tSPACE INVADERS or *1:CHEMSIM 



9.5.5 Abbreviated program names 

When using these two commands (/ and t ) under DOS SUPPORT or UNIVERSAL WEDGE, the 
program name need not be spelt out in full. Only the first letter or so need be typed, followed by an 
asterisk: 



/CHEMSIM 


or 


/CHEM* 


tSYSTEM 


or 


fSY* 


TSPACE INVADERS 


or 


ts* 



Note however that the machine will load the first program it comes to whose name meets this 
abbreviated specification. Thus the command 

/S* 

will cause the machine to load the first file it finds whose name begins with S. Enough letters should 
therefore be given to distinguish the file from any other which may be present on either drive. 

To avoid difficulties of this type, a special form of the directory command may be found useful: 
this is of the form 

@$drno: string* 

e.g. @$:CH* @$1:SIM* or >$:CHEM* 

This command causes to be displayed all file names on the drive specified (or on both drives, if no 
drive number is given) which begin with the letter or string of letters included in the command. 

9.5.6 COPY and SCRATCH with UNIVERSAL WEDGE 

The "copy all files" command may be abbreviated to:- 
>C1 = 

or @C1 = 

Either of these formats will copy all files from drive to drive 1 . 

Also 

S1:AA* is the shortened version of SCRATCH the program (or programs) on drive 
1 which start with "AA". 

9.5.7 Error messages 

When an error message appears on the screen, the use of the command 

> or @ 
will cause an explanatory message to be displayed (although in fact this may be of little help!). 
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9.6 USING THE COMPUTHINK DISK DRIVE 

The Computhink disk drive unit is also designed for use with five inch mini floppy disks. The unit 
operates with the aid of a ROM based system called 'DISKMON" and users are advised to read the 
DISKMON USER'S GUIDE which is supplied with the system. 

The following set of instructions constitutes a brief summary of DISKMON commands and is 
designed to help the beginner get off the ground. 

9.6.1 Starting up 

(a) Check that both the PET and the disk drive unit are switched off. 

(b) Switch on the PET. 

(c) Switch on the disk drive unit. (When switching off, switch off the disk drive unit first.) 

(d) To initialize the "DISKMON" operating system type the instruction SYS 45056 followed by 
the RETURN key. 

(e) Insert the disk or disks and close the drive door(s). The disk should be inserted with the 
manufacturer's label on the bottom right hand corner nearest the user. 

9.6.2 Using a new disk 

Before being used for the first time the disk should be "formatted"; this process divides the disk into 
40 sections and normally not more than one program (file) is stored in each section. Long programs 
may take more than one section. 

The "format" command is 

$F,drno 

drno will be either 1 or 2. The left-hand drive is number 1. 

NOTE. The formatting procedures of the Computhink and the CBM drive units are different 
and this means that disks are not interchangeable. 

9.6.3 The disk directory 

The directory may be inspected by means of the command 
$D,drno 

9.6.4 Loading a program from disk to PET memory 

A program may be loaded by using the command 
$L,drno,"program name" 
The program name will usually be established by referring to the directory. 

9.6.5 Saving a program on disk 

A program in PET memory may be saved on disk by using the command 

$S,drno,"program name" 

Program names may be up to 16 characters long. 

Programs may also be saved in place of existing programs by using the same name. This 
effectively erases the original. 
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9.6.6 Erasing a program from disk 

A program may be erased by using the command 

$E,drno,"program name" 

The DISKMON operating system also supports a number of additional commands and BASIC 
instructions, which may be used when the operator has had some experience. The DISKMON 
USER'S GUIDE should be consulted for further information. 

The Computhink system is supplied with a demonstration disk which contains a number of utility 
programs. The most useful program for the beginner is perhaps DISKCOPY which enables the full 
contents of a disk to be copied directly on to a second disk. 



CHAPTER 10 
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Data Storage on Cassette 



10. 1 DATA FILES AND THE CASSETTE RECORDER 

In order to communicate with peripherals such as the disk drive or cassette recorder, the PET uses 
logical files. Logical files are fully described in Chapter 7 so in this section we shall merely introduce 
the syntax and describe the procedures which are used to write and read data files on tape. 

Of course, the simplest use of the cassette recorder is for the storage of programs ("program 
files") with the aid of the familiar LOAD and SAVE commands. In this case, the user is not concerned 
with the methods which the PET employs in order to organise the program into the individual bits of 
data which are sequentially stored on the tape. The use of the "data file" is an alternative approach to 
information storage on tape. The user can save large numbers of data items (numbers and/or strings) 
in an economical way and can also exercise a greater amount of control over the format of the data on 
the tape. 

The"data file" is usually created and managed with the aid of a BASIC program and there are 
several commands in PET BASIC which are reserved for use with data files. 

10.2 THE OPEN SYNTAX FOR CASSETTE DATA FILES 

In this section we shall first describe the syntax which is used to manage a data file and then give 
examples of typical programs which will enable the user to write data files involving numbers and 
strings as data items. 

It is first necessary to OPEN a logical file through which we will communicate with the cassette 
recorder. The OPEN command not only opens the file to a specified peripheral, but also determines 
the mode of operation of the peripheral. The general form of the OPEN command here is:- 

OPEN lfn,pa,sa,"filename" 

lfn is the logical file number which is chosen by the programmer and may take any value in the 
range 1 to 255. In practice low numbers are used and the programmer often chooses to make the 
logical file number the same as the device number. 

pa, the primary address or device number is fixed by the manufacturer. For the cassette recorder 
pa can take the value 1 or 2. 

The PET has two cassette ports, with device numbers 1 and 2, into which the user can plug a 
cassette recorder. The second cassette port is sometimes (on 3000 series models) located inside the 
computer and the user would require a screwdriver in order to use the facility. This port is located on 
the right hand side of the machine chassis for 4000 series models. Early PETs with built-in cassette 
recorders made use of an internal connection port; the built-in cassette is device number 1. 

The sa part of the OPEN command is the secondary address. The number assigned here 
determines the mode of operation of the peripheral. In this case we need to establish whether the 
cassette tape is to be "written" or "read" and the "sa" value can be 0, 1 or 2. A value corresponds to 
the "read" function (LOAD for a program file) and the PET is instructed to load the data contained 
on a data file which has previously been stored on tape. The sa defaults to 0, so that if no value is 
specified and no filename is supplied the PET will read the first data file encountered on the tape. 
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A value of 1 corresponds to the WRITE function (SAVE in the case of a program file). If a value 
of 1 is chosen, the PET will automatically put an end-of-file (EOF) marker on the tape at the end of 
the data when the file is written. If necessary, further files can then be saved on the same tape. 

A secondary address value of 2 also corresponds to the WRITE function but in this case the PET 
puts an end-of-tape (EOT) marker at the end of the data. 



10.2. 1 Examples of OPEN commands used for tape management 

OPENl,l 

The logical file number here is 1. 
The device number corresponds to cassette port 1. 

No secondary address is specified so a default value of is assumed, i.e. the instruction is to read a data 
file. No filename is specified so the PET will read the first data file encountered on the tape. 

OPEN1,1,0,"NAME" 

In this case the full syntax is used and the PET is instructed to read from tape the data file called 

NAME. 

OPENl,l,l 

Here we specify, by giving the secondary address a value of 1 that we require to write a file with an 
end of file marker. 

OPENl,l,2,"NAME" 

The secondary address value 2 indicates that we wish to write a data file called NAME, with an 
end of tape marker. 

OPEN9,2,l,"NAME" 

Here the logical file number has been chosen to be 9, the device number corresponds to the 
second cassette port and the write instruction is given, together with a file name. 

After issuing the OPEN command it is necessary to include in the program a separate instruction 
to write some specified data on to the tape. This instruction is the PRINT#command which must be 
typed in full and can not be abbreviated to ?#. The full format of this command is 

PRINT#lfn,variable 

The file number must be the same as that specified in the OPEN command and the variable can 
be either a number or a string. 

Finally it is necessary to CLOSE the logical file, signifying the end of the data file. The PET will 
incorporate either an end-of-file or an end-of-tape marker on the tape when the file is closed, 
according to the secondary address used in the OPEN statement. 



10.3 WRITING A DATA FILE 

The following program indicates how these file management commands can be used to create a 
simple numeric data file. 
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Example 10.1 



1 08 
11© 
126 
138 
148 
158 
168 
178 
188 
1 98 
288 
218 



REM WRITE DATA FILE OH TAPE 
REM *********************** 
REM NUMERIC DATA 
REM ************ 



OPEN 1,1.1 
FOR H=l TO 
PRINT#1,H 

he:«:t n 

CLOSE 1 

PR I NT "DATA 

END 



15 



FILE COMPLETE" 



In this introductory example we have used the OPEN syntax without a file name; the secondary 
address used ensures that an end of file marker is sent to the tape when the file is closed. The FOR . . . 
NEXT loop increments N from 1 to 15 and each number is sent to the tape as a separate data item. 
There is a carriage return between each item; the PET therefore sends a carriage return marker to the 
tape so that each item can be identified separately when the tape is read. 

An interface block of memory called the cassette buffer exists between the cassette recorder and 
the main PET memory. During the write process the PRINT # command transfers data to the buffer 
and when the buffer is full a block of data (191 bytes) is sent to the recorder. The tape spools stop 
periodically whilst the cassette buffer is accepting data. When the file is closed the last items of data 
are sent to the tape and the recorder motor is switched off. 

Data items may be sent as strings and the next example illustrates a simple technique for writing a 
string data file. 



Example 10.2 



1 88 

110 

128 
130 
148 
1 58 
168 
170 
138 
198 
288 
218 
228 
238 



REM WRITING DRTR FILES ON TRPE 

REM ************************** 
REM FOR STRING DRTfl 
REM *************** 



0PEN2 , 1 
FOR S=l 
READ A* 
PRINT#2 

ne:kt S 

CL0SE2 

PR I NT "STRING 

DRTfl WRITING 

END 



, 2, "STRING 
TO 6 

,fl* 



FILE 
SOME ., 



FILE" 



COMPLETE" 
STRINGS, ON, 



TAPE, DEMO 



In this example the OPEN format includes a file name and the secondary address 2 ensures that 
an end of tape marker is sent to the tape. 
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The string items are managed with READ . . DATA commands and as in the previous example 
the items are separated by carriage returns. 

It is also possible to write a data file which contains more than one string entry per record by 
introducing item separators, as illustrated in the following example. 

Example 10.3 

106 REM WRITE DATA FILE 

110 REM *************** 

120 REM WITH ITEM SEPARATORS 

130 REM ******************** 

140 : 

1 50 OPEN 1,1,1," STR I NGS " 

160 FOR J=l TO 3 

170 INPUT fl*,B* 

ISO PRINT#l,fl$.?",";B* 

190 NEXT J 

200 CLOSE 1 

210 PR I NT "DATA FILE COMPLETE" 

220 END 

Two strings are entered by means of the INPUT command at line 170. The PRINT# statement 
contains the two strings separated by a comma (in quotation marks) and semicolons. The comma in 
quotes could be replaced by CHR$(44) which is the equivalent ASCII code representation. 



10.4 READING A DATA FILE 

In order to read a data file the OPEN command must contain a secondary address of and the 
PRINT# command be replaced by an INPUT# command. Otherwise the programming techniques 
are similar to those employed in the writing process. 

Example 10.4 

100 REM READ DATA FILE ON TAPE 

110 REM ********************** 

120 REM NUMERIC DATA 

130 REM ************ 

140 : 

150 OPEN 1,1 

160 FOR N=l TO 15 

170 INPUT#1,P 

ISO PRINTP 

190 NEXT N 

200 CLOSE 1 

210 PR I NT "DATA FILE READ COMPLETE" 



.<£.►_' 



END 



This example demonstrates a simple program which can be used to read the numeric data file 
which was produced in Example 10.1. The numeric data are printed on screen at line 180. 
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Example 10.5 



100 REM READING DATA FILES ON TAPE 

1 1 REM ************************** 

120 REM STRING DflTFl 

130 REM *********** 

148 : 

150 0PEN2, 1,0, "STRING FILE" 

160 F0RI=1T06 

170 INPUT#2,fl*a> 

180 PRINTfl*c:i> 

190 NEXT I 

200 CL0SE2 

210 PR I NT "STRING FILE COMPLETE 

220 END 

The string data file which was written in Example 10.2 is read by means of the INPUT#2 
command at line 1 70. The incoming data items are stored in an array and the strings can then be 
ordered, printed etc., as required. 

The next example shows a method of reading the string data file which included item separators. 
Example 10.6 



100 


REM READ DATA FILE 


110 


REM *************** 


120 


REM WITH ITEM SEPARATORS 


130 


REM ******************** 


140 


: 


1 56 


OPEN 1,1,0, " STR I NGS " 


160 


FOR J=l TO 3 


1 70 


INPUT#l,fl*,B* 


ISO 


PRINTfl*;" ";B* 


190 


NEXT J 


200 


CLOSE 1 


210 


PR I NT "DATA FILE READ COMPLETE' 


220 


END 



GET# is an alternative form of INPUT#-GET# transfers one character at a time through the 
input buffer into memory and unlike INPUT# does not fill up the 191 bytes memory in the input 
buffer. It is possible to use GET# in order to check for individual items of data in the file; this can 
provide a useful data management facility. 
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Data Files on 



11.1 SEQUENTIAL, RELATIVE AND USER FILES 

Data, as well as programs, can be stored on disk. There are three main types of data file available to 
the PET user - sequential, relative and user files. Of these, the relative file is available only to users of 
BASIC 4.0 together with Disk Operating System 2.0 or 2.5, i.e. on 4000 and 8000 series machines, or 
on upgraded earlier models. 

In any file, there will be a number of "records". A record is the electronic equivalent of a file card, 
and consists of a number of items of data. For instance, in an address file, each record might contain 
the name, address and telephone number of one person. Each separate item within a record is termed 
a data "field" - thus the name, address and telephone number in our address file would each occupy a 
separate field. Clearly the lengths of the different fields in a record will not usually be the same. 

In a sequential file it is not possible to access a single item from the file directly; the file must be 
read through from the beginning to identify the appropriate entry. If the file is sufficiently small to be 
stored in its entirety in machine memory this may not present a major problem, but for very large files 
it may be a serious disadvantage. In many applications, however, "random access' or "direct access" 
to individual records is not required, and in such a case a sequential file may be perfectly satisfactory. 
Examples might be a school class list, or the payroll of a firm, where it is in any case necessary to access 
every item on the file each time the file is used. Sequential files have the by no means negligible 
advantages that they occupy significantly less space than do direct-access files and that when one item 
has been dealt with, no time is wasted searching for the next entry. Historically, the widespread use of 
sequential files is at least partly due to the use of such data storage media as magnetic tape or punched 
paper tape, where access to data is by the very nature of the medium sequential. 

Once the length of the file becomes greater than about 30 kbytes, it will usually be found 
worthwhile to use a random-access file rather than a sequential file, except for purely sequential 
applications such as those mentioned above. There are two types of random-access or direct-access 
file - "relative" and "user" files. 

In a relative file the user can pick out any record from the file relative to the beginning of the file. 
This gives the user direct access to any desired record; he can also, if desired, read through the records 
sequentially, just as with a sequential file. The major disadvantage of the relative file in comparison 
with the sequential file is that it will normally occupy significantly more space on the storage medium. 
This is because it is usual to allow the same amount of space for every record, regardless of the actual 
number of characters to be entered. Thus, in our address file, the space allocated to the name must be 
sufficiently large to hold the longest name likely to be encountered. (If you have friends or customers 
with names like "Montmorency Marmaduke Featherstonehaugh-Urquhart", this can clearly be a 
serious problem, since John and Fred Smith will have to be allocated just as much space on the disk as 
the polysyllabic gentleman aforesaid.) To make the records of variable length would be very compli- 
cated, especially when entries are liable to be changed at a later date. (In a sequential file, where each 
record is allocated precisely the required amount of space, the whole file must be rewritten whenever 
an entry is to be updated.) 

For those unfortunates without BASIC 4.0, it is possible to construct direct-access files, but the 
process is rather complicated, since the program must allocate in detail the disk space required for 
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each entry, and keep a detailed record of the position on the disk of each item of information. The 
creation of such "user" files is dealt with later, but if considerable work is to be carried out with 
random-access files, it will almost certainly pay the user to have his system upgraded. A further 
disadvantage of user files is that, unless the user is prepared to indulge in some rather complicated 
programming, they tend to occupy considerably more space even than relative files. 

11.2 INDEXING RANDOM-ACCESS FILES 

When accessing direct-access files, we may wish to select records according to a number of possible 
criteria. In the case of a small file, we can just read the appropriate field of every record in turn - rather 
like searching a sequential file. The difference is that with a sequential file the whole of each record 
must be read in turn, whereas with a direct-access file we need access only the appropriate field of each 
record. Where the file is large, however, this can take an excessively long time. 

Where a large file must be repeatedly searched in this way, it is convenient to order it. However, 
each record may contain a number of fields, and on different occasions we may need to search the field 
for different characteristics. For example, in a library catalogue we may search for a book by name, or 
by subject, or by the author's name. Similarly, if a general practitioner were to keep a record of his 
patients, he might need to search the record by name or age, or by the patients' ailments, or by the 
drugs prescribed. 

In such a case it is usual to prepare a separate index for each characteristic or 'key'; each index is 
then sorted into alphabetic or numerical order to simplify future reference. Of course, each index is 
itself a separate file, which must be separately stored. These index files will in general be much shorter 
than the main file however, since each entry will consist only of the key and the file record number. 
According to the size of the index file, it may be either sequential or relative. A sequential file will in 
general occupy less space, but must be searched in strict sequence, whereas more sophisticated search 
strategies - e.g. the binary search - may be used on a relative file. In a binary search, the file is 
repeatedly divided into two, and a decision is taken as to which half contains the first of the wanted 
entries. This process is repeated until the first of the desired entries is located. The process is 
essentially similar to that unconsciously adopted by most people when seeking a word in a dictionary. 
The equivalent of a sequential search would be to scan each word in turn, starting with 'aardvark' and 
continuing until the required word is found - clearly not the speediest method, although very reliable, 
and easier to program. 

1 1. 3 ERROR MESSAGES 

Should something go wrong with an attempt to carry out any disk operation, the disk controller can 
send an error message to the PET. 

With BASIC 4.0 the process is quite straightforward, since the error message consists of a single 
string which can be read directly, without opening a special command and error channel to the disk 
controller. This is done by means of the command 

PRINTDS$ 

Since each of the various possible error messages begins with a different number, it is often 
convenient to read only the numerical part of the message, using the numerical variable DS; messages 
with numbers below 20 can in general be ignored. The skeleton of a typical BASIC 4.0 disk error 
subroutine would thus be: 

nnn GOSUB 10000 

i 
i 
i 
i 
i 
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10000 IFDS<20 THEN RETURN 

10010 PRINTDS$ 

10020 END 

On systems using BASIC 2.0 the process is somewhat more complicated, since the message 
consists of three numerical variables and a string variable, and these must be accessed via the special 
command and error channel (secondary address =15). 

The complete error message consists as before of a number and the error message itself, but two 
more numbers indicating where applicable the track and sector at which the fault occurred, are also 
output. 

A complete BASIC 2.0 disk error subroutine might be: 

nnn OPEN15,8,15 



nnn 


i 
GOSUB 1000 
1 
1 


1010 


1 
INPUT#15 EN,EM$,ET,ES 


1020 


IF EN=0 THEN RETURN 


1030 


PRINT EN;EM$,ET,ES 


1040 


CLOSE 15 


1050 


END 



In many applications a knowledge of the track and sector where failure occurred, and of the error 
message number, is not helpful. In this case line 1030 may be simplified to 

1030 PRINT EM$ 

11.4 USING SEQUENTIAL DISK FILES 

11.4.1 Creating, updating or reading from a sequential file 

A sequential file is opened by a command of the general form: 
OPEN lfn, pa, sa, "driveno:filename, filetype, mode" 

lfn is the logical file number, which as always may be selected by the programmer. It must be in the 
range 1 - 255. 

pa is the device number or primary address - normally 8 for the CBM disk drive. 

sa is the secondary address, which may be selected at will by the programmer, within the range 2-14. 

driveno will be either or 1, according to which of the two drives contains the disk to be used. 

The file name must not exceed 16 characters in length. 

Since we are here working with sequential files the file type will be SEQ, for sequential (this may 
be abbreviated to S). 

The mode indicates whether the program is to WRITE data into the file or READ from it 
(usually abbreviated to W or R respectively). 
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The command for the opening of a new sequential file to be called "NAMES", on a disk placed in 
drive 0, would thus be 

OPEN2,8,2,"0:NAMES,S,W" 

If we later wished to open the same file for reading, we might use: 

OPEN3,8,3,"0:NAMES,S,R" 

Of course, the same logical file number cannot be used for two different logical files at the same 
time, and if a file is to be kept open for both reading and writing, two separate logical files must be 
opened - one for each mode. 

1 1. 4. 2 Interactive Commands 

The command strings required to open a file may be assembled by concatenating shorter strings within 
the program. A program can thus ask the user for the name of a file, the drive in which the relevant 
disk has been placed and so on, before OPENing a logical file. This is seen in the demonstration 
programs WRITEDATAFILE and ORDERPRINT (Examples 11.1 and 11.2). 

Once a file has been opened, data are written to or read from it using the PRINT#, INPUT# or 
GET# commands. 

For example: 

OPEN3,8,3,"0:FILE,S,R" 
INPUT#3,Z$(1) 

or: 

OPEN6,8,6,"l:ANOTHERFILE,S,W" 
PRINT#6,N,Z$,P 

Example 11 .1 

WRITEDATAFILE 

This demonstration program illustrates the process of creating or updating a file. For simplicity the file 
used consists simply of a list of strings. This list might for example be a file of customer names, or a 
school class list. 

180 REM *************** 

110 REM *WRITEBATAFILE* 

120 REM * E.fl.FLINN * 

130 REM * MRV 1982 * 

140 REM *************** 

150 

160 REM THIS PROGRAM CREATES OR UPDATES A SEQUENTIAL DATA Fit F 

170 

180 REM THE DATA STORED CONSISTS OF A SERIES OF TEXT STRINGS (E.G. NAMES > 

190 

290 PR I NT " r3" = PR INT: PR INT: pp i NT : 

210 INPUT "WHICH DRIVE - OR 1";D* 

220 

230 REM OPEN ERROR CHANNEL 

240 OPEN 15, 8, 15 

250 

260 REM INITIALISE DRIVE 

270 PRINT#15, "I"+D* 

280 

290 INPUT "MW8HRME OF FILE";N* 

380 X$=M+" : "+N*+" , S, W" 

310 PR I NT: PR I NT -PR I NT: 
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328 INPUT "HEW FILE QD OR OLD (0>".;F* 

330 l*=left*<:f*.. n 

MB IF L*0"N" RND L*O"0" THEN PRINT "MMS" : GOTO 326 

350 REM 

360 REM OPEN FILE 

3?0 REM 

380 IF L*="0"THEN PRINT#i5, "S"+D*+" : "+N* 

390 0PEN2,8,2..X* 

400 GOSUE 590 

4 1 PR I NT " IT' : PR I NT : PR I NT : 

420 INPUT "NUMBER OF ENTRIES" ;N 

438 PRINT#2,N 

44m GOSUB 596 

450 PR I NT " 3" : PR INT: rr i NT : PR I NT : 

460 PRINT" 3UNPUT LIST OF NAMES ..TERM I NAT I NO EACH BY fl CARRIAGE RETURN.", 

470 PRINT" SHAMES MUST NOT INCLUDE COLONS OR COMMAS." 

480 CR*=CHR*a3> 

490 FORI=i TO N 

500 INPUT A* 

510 PRINT#2,fi*.;CR*.; 

=i2fl GOSUB 590 

530 NEXT I 

540 CL0SE2 

550 CLOSE 15 

566 END 

570 REM CHECK FOR DISK ERRORS 

580 REM ***** *** **** ****** 

590 I NPUT# 1 5 .. EN* .. EM*, ET* , ES* 

600 IF EN*="00" THEN RETURN 

610 PR I NT: PR I NT: PR I NT 

620 PRIHTEM*,EN* ET*,ES* 

630 CL0SE2 

640 CLOSE 15 

650 END 

The program first asks the user for the number of the drive containing the disk on which the file is 
to be written (line 210). It next opens a command and error channel to the appropriate disk drive (line 
240) and initialises the disk (line 270). 

It then asks the user for the name to be allocated to the file, and assembles the string to be used in 
the OPEN command (lines 290 and 300) . If the file is an up-dated version of a file already on the disk, 
the original version must be deleted or "scratched" (line 380). 

The new file is then opened (line 390), using the string assembled from the information which has 
been input by the user. 

Note that at this stage the error channel is checked (line 400). This is done every time a disk 
operation is carried out - i.e. every time an item of information is read from or written to the disk. If a 
disk error occurs, the logical files which have been opened are closed, and the program ENDS (lines 
630, 640, 650). 

Now that the file has been opened, we can write data into it. The first item to be stored is the 
number of entries to be made in the file (lines 420 and 430). This information is not strictly necessary 
for the process of writing a file, but is useful when the file is to be read back. (This is seen in the next 
program ORDERPRINT. In ORDERPRINT the entries are read from disk and stored as indexed 
string variables within the PET; it is therefore necessary to know the number of entries so that the 
array can be appropriately dimensioned.) 

Each entry in turn is then input by the user and transferred to disk (lines 480 - 520), the error 
channel being checked at every step (line 520) to ensure that no write errors have occurred. Finally 
the logical files are closed and the program ENDs (lines 540-560). 

Note that in line 5 1 0, each string written to the disk is followed by a carriage return - CHR$( 1 3) . 
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This is required by the disk drive software, to indicate the end of the entry. The semicolons suppress 
the normal line-feed with carriage return which would otherwise be written to the disk by the PET at 
the end of the PRINT# statement. This precaution is not always essential, but is good practice, since 
otherwise the line feed - CHR$( 1 0) - will be written at the head of the next entry. Often this will not 
matter, but if the data are to be sorted alphabetically after being read in from disk, and combined with 
other inputs from the keyboard, the extra character may well upset the sort. 

If more than one item is to be entered at a time - e.g. a name and a telephone number - then the 
separator between the items must be enclosed in quotes: for example 

PRINT#8,A$","B$;CHR$(13); 

Where a number is to be written to disk as part of such a command, the number is best expressed 
as a string, using if necessary the STR$ function. For example: 

INPUT A$,B 

PRINT#1,A$","STR$(B);CHR$(13); 

N.B. Since this program and the following program ORDERPRINT are intended purely as 
demonstrations of the techniques necessary to write data to disk and recover it, they have been kept as 
simple as possible. In a real program, precautions such as those detailed in Chapter 12, "Interactive 
Programming", would be required. It would also normally be necessary to make provision for 
NEWing a disk, so as to allow the use of a new and unformatted disk, or the re-use of an old disk. 

Example 11.2 

ORDERPRINT 

This program shows how data stored in a sequential file may be extracted and used. Data are read in 
from a file created by the use of program 1 1 . 1 . It is assumed that the strings read in consist of a school 
class list. The user inputs an examination mark for each name; the students are then sorted into mark 
order, and their names are printed out, together with their marks and ranking. This shows how even a 
very simple data file can be utilised in practice. The program also demonstrates the usefulness of the 
formatting facilities on the PET printer. 

100 REM ************ 

110 REM *ORDERPRINT* 

120 REM ************ 

130 REM 

140 REM 

156 REM THIS PROGRAM READS IN NAMES' FROM AN EXISTING FILE 

160 REM 

170 REM 

180 REM THE USER INPUTS MARKS, AND THE NAMES ARE PRINTED OUT IN MARK ORDER 

190 REM 

200 GfiSI 'E 700 

210 OPEN 15, 8, 15 

220 PRINT#15,"I"+D$ 

230 X$=B$+"- "+N#+".S.P" 

240 0PEN2,3,2,X* 

250 INPUT#2,N 

260 GOSUE 790 

270 PRINT'-MCHUMBER IN SAMPLE = ";N 

280 PRINT 

290 PRINT 

300 DIM A<N>:DIM BCN^DIM Z*<N> 

310 FOR K=l TO H 

320 INPUT#2,Z*<K> 
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330 GOSUB790 

348 PRINT 2*<K>.;TAB<35> : INPUT A<K>:B<K>=K 

350 PRINT 

360 NEXT K 

370 CL0SE2 

330 CLOSE 15 

390 REM SORT NAMES INTO MARK ORDER 

400 REM **** ***** **** **** ***** 

410 FOR P-l TO N 

420 FOR K=l TO N-P 

430 IF FKK»=fKK+l> THEN GOTO 466 

440 X=A<K> : A<K>=A<K+1> : A<K+1>=X 

450 V=B<K> :B<K::'=B<K+1>:B<K+1>=V 

460 NEXT K 

470 NEXT P 

4S0 REM CHECK FOR EQUAL MARKS 

490 REM ***** *** ***** ***** 

590 FOR K=l TO H 

!=ilfi CCK>=K 

520 IF fl<K>=fl<K-i> THEN C<K>=C<K-1> 

530 NEXT K 

540 REM 

559 OPEN 4.. 4 

560 OPEH1.. 4,1 
570 OPENS, 4, 2 

580 F*=" AAAAAAAAAAAAAAAAAAA 993 999" 

590 PRINT#3,F* 

600PRINT#4," NAME MARK POSITION" 

610 PRINT#4, " **** **** ********" 

620 FOR K=l TO H 

630 PRINT#1,Z*<B<K>::';CHR*'::29>,A<K>,CCK> 

640 NEXT K 

650 PRINT#4 

G&B CLOSE 1 

670 CLOSES 

680 CL0SE4 

€3Q END 

700 PR I NT "3 LISTING AND ORDERING PROGRAMME" 

710 PRINT" ******* *** ******** *********" 

726 INPUT ir *K&»-iBME OF DATA FILE".:N* 

730 INPUT "MSWWHICH DRIVE HOLDS DATA FILE - 8 OR 1";D* 

740 PRINT'TIdftftEHTER APPROPRIATE MARK AGAINST NAMESW 

750 PR I NT "PROGRAMME ORDERS NAMES IN MARK ORDER, HIGHEST FIRST" 

760 RETURN 

770 REM READ ERROR CHANNEL 

7S0 REM **** ***** ******* 

790 I HPUTtt 1 5 , EN* , EM* , ES* , ET* 

300 IF EN*="00" THEN RETURN 

810 PR I NT "MSB I SK ERRORS" 

820 PRINT EH*,EH*,ES$,ET* 

830 CL0SE2 

340 CLOSE 15 

350 END 

As before, the user is asked to specify the number of the drive containing the disk, and the name 
of the file to be accessed (lines 720 and 730). These items of information are used (lines 220-230) to 
initialise the drive and to form a string for use in the command which opens the file for reading. The 
number of names in the file is read in (line 250), and used to dimension the arrays used within the 
program (line 300). The names are then read in turn, the error channel being checked after every 
operation, and assigned to the subscripted string variable Z$. Each name in turn is then displayed on 
the screen so that the user can input the appropriate mark (line 340). When all the marks have been 
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input the names are sorted into mark order (lines 410-470). Since it is assumed that the size of the class 
will be reasonably small, speed of sorting is relatively unimportant, and a bubble sort has therefore 
been used for simplicity. In other applications it might well be necessary to use a speedier and more 
efficient sort routine. 

Once the class has been sorted into mark order, channels to the printer are opened, and the 
names, marks and class placings are printed out using a suitable format (lines 550-690). 

It will thus be seen that sequential data files are relatively straightforward in use, and lend 
themselves well to many routine clerical or administrative applications. 

11.5 RANDOM-ACCESS FILES: RELATIVE AND USER FILES 

In a sequential file, such as those dealt with in the preceding section, all the items are read in order. 
Where we wish to inspect or alter only a single record somewhere in the middle of the file, this clearly 
wastes a considerable amount of time. Once the file exceeds 30-40 kbytes, the delay becomes 
excessive, and a "random-access" or "direct-access" file will normally be preferred. Even where a 
random-access file is constructed however - as for a catalogue or a directory - it is quite common for 
the index file or files, from which the location of the desired record can be found, to be sequential. 

Random-access files can be constructed on a PET system - relatively easily on systems using 
BASIC 4.0, such as the 4000- and 8000-series or updated earlier machines, and with rather more 
difficulty on unmodified early machines using BASIC 2.0. 

On machines using DOS (disk operating system) 2.0 or 2.5, "relative files" can be constructed, 
using a set of commands not unlike those used in connection with sequential files. On earlier machines 
it is necessary for the program to take direct control of the process by which data is written to 
individual locations on the disk, and to keep a record of precisely where on the disk each item of data is 
stored. The use of such "user files" is clearly a more complicated business, and where the system 
allows, relative files will normally be preferred for their simplicity. Both user files and relative files are 
available with DOS 2.0 and 2.5 (i.e. on 4000- and 8000-series machines,) while earlier versions of 
DOS allow only user files. 

11.6 RELATIVE FILES 

The principle of a relative file is identical with that of the user files discussed in the next section. 
However, most of the "housekeeping" required to write data to the disk, and to keep track of the 
physical location of specific entries, is carried out by the operating system, so saving the programmer a 
considerable amount of effort. 

To simplify the handling of random-access files, whether relative or user, it is usual to allocate the 
same space on the disk to each record, regardless of possible variations in length of the individual data 
items within each record. Thus, in an address file, the space allocated to the name will in every case be 
sufficiently large to hold the longest name likely to be encountered, even though this means that in 
most cases a considerable amount of disk space will be wasted. 

In a sequential file, each entry is given the exact amount of space necessary to accommodate the 
entry: a random- access file therefore always occupies more disk space than a sequential file containing 
the same data. On the other hand, a single entry in a random-access file can readily be modified, 
whereas a sequential file must be completely re-written in order to carry out even the most minute 
alteration. These facts will be seen more clearly after studying the simple demonstration programs 
which follow. Let us look at the instructions necessary to open, modify and use a relative file. 

To create a relative file, we use the command DOPEN#. The file is then "initialised" - i.e. the 
character CHR$(255) is written into the first character position of the space allocated to each record. 
(255 is the ASCII representation of the symbol v , which is unlikely to be used in the normal course of 
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events.) The number of locations reserved at this stage should be adequate to allow for any additions 
to the file which may later become necessary. This ensures that the disk operating system will reserve 
sufficient space on the disk for such later entries. Even where space has not been specifically reserved 
in this way, a file can readily be expanded at a later date. Clearly, however, this process will depend on 
the availability of sufficient space on the disk, and it is wiser to make adequate provision for expansion 
when the file is first created. 

Once a relative file has been created, records can be entered. This can be done one by one, as 
required - all the records need not be entered at once. 

Once a relative file has been created, it can be re-opened for subsequent access using the normal 
OPEN command; the command string necessary for this can, as in programs 11.1 and 1 1 .2, be built up 
from data items entered from the keyboard. Entries in the file may then be made, altered, or simply 
read, as required. 

11.6.1 Creating and Initialising a Relative File 

DOPEN# A relative file is created by means of the command DOPEN#, which is available only in 
BASIC 4.0 (i.e. on 4000- and 8000-series machines, or upgraded earlier models). The format for use 
with relative files is: 

DOPEN # lfn,'filename",Ddrno, Lrlen 

The logical file number lfn may, as usual, have any value from 1 to 255; drno, the drive number, 
must be or 1 ; rlen is the length of each record in bytes. The record length may take any value from 1 
byte upwards, provided that the overall size of the file does not exceed 182,880 bytes (i.e. 720 
254-byte blocks) 

DOPEN#l,"INCOME TAX",D1,L200 

would thus open on drive 1 a file named "INCOME TAX'", with a length of 200 bytes for each record 
on the file. Future operations on the file would then be carried out using the logical file number - in 
this case 1. 

Note that at this point, although the length of each individual record within the file has been 
specified, the total number of records to be contained in the file has not. The initialisation process sets 
the length of the file, but before we can examine this process we must first consider the RECORD# 
command. Using this we may specify any desired number of records up to 64K (65,536). 

RECORD # -. The file pointer. When writing to or reading from a random-access file, it is 
necessary to be able to specify the precise point in the file at which the next input or output operation is 
to begin. Both the record which is to be accessed, and the point within the record (i.e. the character 
within the record) at which the operation is to start, must be specified. This is done using a "file 
pointer" - an indicator which "points" at the appropriate character in the relevant record. The file 
pointer is positioned using the RECORD# command. The complete syntax of this command is 

RECORD # lfn,recno,charno 

lfn is the logical file number assigned in the DOPEN# statement, recno is the record number, which 
may have any value between 1 and 65,535 (i.e. 64K), and charno is the position of the character within 
the record to which the pointer is to be set. charno may have any value from 1 to 254. If no value is 
entered, charno is taken as 1 (the "default value"). 

Thus, if we wish to set the file pointer to the first character in the sixtieth record of a file which has 
been opened under the logical file number 7, the command will be: 

RECORD#7,60,1 

or just RECORD#7,60 
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If we wish to set the pointer to the 27th character of the same record, the command will be: 
RECORD#7,60,27 

A useful modification of the RECORD# command allows us to access different records under 
program control. The command 

RECORD#7,(N),39 

will set the file pointer to the 39th character of the Nth record in the file, where N is some variable 
whose value can be changed by the program. Any allowed variable name can be used here, but note 
that the variable name must be enclosed in brackets. Once the file has been opened, the number of 
records must be specified. This is done by positioning the file pointer to the first character position of 
the last record in the file, using the RECORD# command, and then writing into that record the 
character CHR$(255). When this is done, the DOS will detect that all the other records are empty, 
and automatically write CHR$(255) into each, so initialising every record. Once a file has been 
opened and initialised, we may go on to enter data. Alternatively, the file may be closed, leaving it 
available for data entry at some later time. This is done by means of the command 

DCLOSE#lfn 

Example 11.3 

A basic, though incomplete, program to create a relative file called "RELFILE", containing 75 

entries each of 60 bytes, and located on the disk in drive 1, would be: 

I £10 DOPEN# 1 , " RELF I LE " , Da , L6@ 
110 RECORD* 1,75 

1 20 PR I NT* 1 , CHR* < 255 > .: 
130 DCLOSEttl 
140 END 

Note the semicolon in line 120; as in program 1, this prevents a terminator (line-feed and carriage 
return) from being transmitted to the file. 

This simple program will reserve space on the disk and in the directory for the file "RELFILE". 
All the entries will as yet be blank, however. 

Example 11.4 

No provision has so far been made for dealing with disk errors; a more complete program would 

therefore be as follows: 

10 REM CREATE lflRELF I LE 

II REN *************** 

1 00 DOPEH* 1 , " RELF I LE " , DO , L66 

110 GOSUB 500 

120 RECORD* 1,75 

130 GOSUB 500 

1 40 PR I NT* 1 , CHR* < 255 > ; 

150 GOSUB 500 

160 DCLOSEttl 

170 END 

500 REM DISK ERROR SUBROUTINE 

510 IF DS<20 OR DS=50 THEN RETURN 

520 PRINTDS* 

530 DCLOSEttl 

540 END 
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An error subroutine of this type should be incorporated in all programs which make use of disk 
files. 

NOTE When RECORD# is used as part of the initialisation process, an error message will be 
displayed, pointing out that the record being accessed does not yet exist. This fact should occasion no 
surprise, and the message may safely be ignored under these circumstances. The number of the error 
message will be 50, and the program above therefore ignores any error message with this number. 

11.6.2 Writing data into a relative Hie 

We may write as many items of data as will fit into each record, by setting the file pointer to the 
correct character position within the record, and then writing in the data by means of a PRINT# 
statement. 

Only strings or string variables can be written to a relative file - numerical variables or numbers 
must be converted to strings (using STR$) before being written into the file. 

Note also that entries to different fields within a record must be made in strict sequence, since 
writing an item to a file causes the remaining space between the end of that data item and the end of 
the file to be overwritten with zeroes. It is therefore not possible to rewrite a single field (except the 
last) within each record; the complete record must be transferred to the PET, modified as necessary, 
and then rewritten to disk by means of the PRINT# instruction. 

Example 11 .5 

Let us consider first of all the problem of entering a single record into an existing file . For convenience 
we shall use the existing file "RELFILE" created in example 1 1.4, with its seventy-five records, each 
capable of holding sixty bytes of data (i.e. 60 characters). Let us assume that the file is to contain, say, 
the names, ages and telephone numbers of various persons. We may then allocate say, 35 characters to 
the name, 3, including the terminator, to the age (few people being older than 99) and the remaining 
22 characters to the telephone number - this should suffice for even the longest number which may be 
encountered. 

Then, if we wish to enter a new record - say Marcia Smith, 26, 061-246-8026 - at record number 
35, a simple program to do this would be: 

10 REM MODI RELFILE 

1 1 REM *********** 

12 REM 

1 00 DOPEN# 1 , " RELF I LE " , D0 

1 1 6 GOSUB 580 

120 G*="MARCIfl SMITH" :A*="26" :T*=" 06 1-246-8026" 

130 RE" SET FILE POINTER TO CHARACTER #1 OF RECORD #35 

140 RECORDtt 1,35: REM DEFAULT CHARACTER POSITION IS 1 

150 GOSUB 500 

160 PRINT#1,G* 

170 GOSUB 500 

ISO RECORD* 1,35, 36: REM SET FILE POINTER TO START OF NEXT FIELD 

190 GOSUB 500 

200 PRINT#l,fl* 

210 GOSUB 500 

220 RECORD** 1,35, 39: REM SET FILE POINTER TO START OF NEXT FIELD 

225 GOSUB 500 

230 PRINT#1,T* 

240 GOSUB 500 

250 DCLOSEttl 

260 END 

500 IF DSC20 THEN RETURN 

510 PRINT DS* 

520 DCLOSE#l 

530 END 
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Example 11.6 

This last program can clearly be developed, allowing us either to enter or to modify at will any specific 
record in the file. We can therefore extend the program to allow the entry in turn of every record in the 
above file. 

18 REM WRITE1RELFILE 

11 REM ************* 

12 REM 

108 PRIHT"3IHSERT DISK IN DRIVE #8" 

128 INPUT "IHUMBER OF ENTRIES ";S 

130 DOPEN#l., "RELFILE".,D8 

148 GOSUB 588 

158 FOR 1=1 TO S 

1 68 RECORD* 1 , < I > 

178 GOSUB 588 

1 88 PR I NT " 3NRME # " I " ? " : I NPUT G* 

185 PRINT#1,G* 

198 GOSUB 588 

288 RECORD* 1 , < I > ., 36 

2 1 8 GOSUB 588 

228 I NPUT "SAGE ";fl* 
222 PR I NT* 1,8* 
225 GOSUB 588 
238 RECORD* 1 ., < I > , 39 

248 GOSUB 588 

245 INPUT "^TELEPHONE NUMBER "rT$ 

246 PRINT#i,T* 
243 GOSUB 588 

249 NEXT I 
258 DCLOSE*l 
268 END 

588 IF DS<28 THEN RETURN 

518 PRINT DS* 
528 DCLOSE*! 
538 END 

Example 11.7 

This shows how any entry may be modified at will. 

18 REM M0D2RELFILE 

11 REM *********** 

12 REM 

188 PRINT"Z]INSERT DISK IN DRIVE *8" 

1 28 DOPEN* 1 ., " RELF I LE " ., D8 

138 INPUT "BWHICH RECORD ";N 

148 GOSUB 588 

1 68 RECORD* 1 ... < N > 

178 GOSUB 588 

188 INPUT "SHAME ".jG* 

185 PRINT*l r G* 
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198 GOSUB 588 

288 RECORD* 1 , < N > , 36 

218 GOSUB 588 

228 INPUT"MRGE " ;fi* 

222 PRINT#l.,Fr* 

225 GOSUB 588 

238 RECORD* 1 ., < N > ., 39 

240 GOSUB 500 

245 INPUT "^TELEPHONE NUMBER ";T* 

246 PRINT#1.,T* 

248 GOSUB 500 

249 INPUT "^FINISHED " ;R*:IF LEFT*<R*, 1 >0"V" THEN GOTO 138 

250 DCLOSEttl 
260 END 

500 IF DSC20 THEN RETURN 

518 PRINT DS* 
520 DCLOSE* 1 
530 END 

11.6.3 Reading data from a relative file 

In the previous programs, each data input statement was terminated by a line feed. This is written to 
the file record, and is recognised as an acceptable terminator by an INPUT# command. We may thus 
read any record, or indeed any field, from the file at will. To open the file for reading, we may again use 
the DOPEN# command; alternatively, we may use the normal OPEN command which we have 
already seen used with sequential files in the previous section. The latter has the advantage that, as in 
the demonstration program ORDERPRINT, we can build up the command by concatenating a series 
of strings. This allows the file name and the drive to be specified from the keyboard, something which 
is not possible if DOPEN # is used. The program which follows - example 11.8- shows this technique 
in use. 

Example 11.8 

1 REM RERD2RELFILE 

2 REM ************ 

3 REM 

180 INPUT "34HICH DRIVE HOLDS DISK".;D$ 

118 INPUT "NAME OF FILE";N* 

1 28 OPEN? , 8 .- 2 ., D*+ " : " +N*+ " , R ,- R " 

1 25 GOSUB 588 

138 PRINT"HWHICH RECORD <F TO FINISH> " .: 

135 INPUT R*:R=VPL'::R*> :IF LEFT*<R* , 1 > = "F" THEN GOTO 178 

148 REC0RD#2.,<R> 

145 GOSUB 588 

158 INPUT#2.,NFlME$ 

155 GOSUB 588 

156 REC0RD#2 ., < R > .- 36: GOSUB 588 

157 INPUT#2.,P.*:G0SUB 588 

1 58 REC0RD#2 .. < R > .. 39 : GOSUB 588 

159 INPUT#2..T*:G0SUB 588 
168 PR I NT "J" NAME* 
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PRINTR*„T* 
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GOTO 130 
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CL0SE2 




180 


END 
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REM READ ERRi 


3R 


500 


IF DS>=20 THEN 


510 


RETURN 




11.6.4 Searching a file 





CHANNEL 

PRINTDS* :CL0SE2 :END 



In this program - READ2RELFILE - only a single field of the specified record is accessed. In the 
example, this is the first field, but it would clearly be equally easy to access any other desired portion of 
each record. This is very useful when the file is to be searched with respect to some specific 
characteristic. For example, to continue with our 'little black book' program, we can very quickly 
search the file for persons of a specified age; their names and telephone numbers can then be listed on 
the printer. This searching process could just as well be carried out on a sequential file but the time 
required would, in the general case, be longer, since it would be necessary to read in the whole of each 
record in turn, rather than just a single (short) field, as here. 

11.6.5 Indexing Random- Access Files 

With a relatively short file such as that used in the exmples, it is quite easy to read through the whole 
file, checking only the required field of each record. With a very large file, however, the time required 
may become inconveniently large, and in such a case it will be more convenient to prepare an index - 
i.e. a list of file entries ordered according to some specified criterion. For instance, our demonstration 
file RELFILE could be indexed with respect to age, or even by location, as indicated by the STD code 
of the telephone numbers. Once an index has been prepared, it is then only necessary to look up the 
required characteristic in the index to obtain all the relevant record numbers. 

11.7 WRITING AND READING SIMPLE USER FILES 

With earlier machines, using BASIC 2.0, the process of writing and accessing direct-access files on the 
CBM disk system, although simple in concept, is in practice complicated by the number and nature of 
the commands which must be used. In the later systems extra facilities are provided which allow 
random-access files to be constructed much more simply than by the direct control of block allocation 
on the disk (see previous section). However, all the direct-access commands are available on the later 
systems, while on earlier (2000- and 3000-series) systems which have not been upgraded, there is no 
alternative to the use of direct-access or 'user' files. The handling of user files will therefore be 
discussed at some length. 

It is usual, for simplicity, to make all the entries in a direct-access file the same size, although in 
general each entry will be divided into a number of 'fields' which will not normally be all of the same 
length. 

For instance, in an address file, the name, address and telephone number might each occupy a 
separate field; clearly the field containing the address would normally be rather larger than that 
containing the telephone number. However, each field must be large enough to accommodate the 
longest name, or the longest address or telephone number, which is likely to be encountered. This 
being so, in most cases there will be a significant amount of waste space within each field. This does not 
occur with a sequential file, since there the length of each entry is known as soon as the entry is 
complete, and no space need be wasted. 

Like a relative file, a user file therefore takes up more space than a sequential file containing the 
same data. On the other hand, an individual entry in a random-access file can be changed at will, 
whereas with a sequential file the whole file must be re-written. 
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To start with, let us consider the simplest possible case, where each entry consists only of a single 
item, and let us allocate one block to each entry. (This is usual, since it greatly simplifies programming, 
although a considerable amount of space may be wasted.) First, however, it will be necessary to 
examine the way in which data is stored in the CBM floppy disk system, since the creation and use of 
user files necessitates a detailed knowledge of the way in which disk space is allocated. 

1 1. 7. 1 Storage of data on PET/CBM floppy disks 

On the 2040, 3040 and 4040 CBM disk drive units, data and programs are stored on a number of 

Figure 11 .1 - see page 129 
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concentric circular tracks. There are 35 such tracks, numbered from 1 to 35. Each track is divided into 
sectors or "blocks", and each block can hold 255 bytes of data. The number of fixed-length blocks on a 
track naturally varies with the circumference of the particular track; the outermost track carries 21 
sectors, numbered to 20, while the innermost track can hold only 17 (numbered to 16). The total 
number of blocks is 690, so that the total usable capacity of the disk is almost 1 80,000 bytes, or about 
30,000 words of English text (the equivalent of a short novel). Several blocks are used by the 
operating system, however, so that the space available to the user is somewhat less. 

The data structure of each block is quite complex. A single file, whether program, sequential, 
Figure 11 .2 - see page 129 
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relative or user, may fill many blocks, which need not necessarily be physically adjacent to one 
another on the disk. Each block therefore contains a two-byte block pointer, which specifies the 
location (i.e. the track and sector) of the next block in the file. A number of other items of information 
used by the DOS (Disk Operating System) are also stored, along with 256 bytes of data. The first byte 
(byte 0) of the 256 is however reserved to indicate the location of the last valid character within the 
block, so that only 255 bytes are available for data storage. 

Track 1 8 of each disk (i.e. the track midway between the innermost and outermost tracks) carries 
a system file. Sector of track 18 holds the "Block Availability Map" or BAM, which carries details of 
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which blocks on the disk are already occupied and which are available for use. This occupies the first 
144 bytes of the block, the remainder being used to store the "directory header" - i.e. the disk name 
and ID. Blocks 1 and 2 are reserved for the file directory proper. 

NB When a disk is initialised, the BAM is read into the memory of the disk controller; at every 
access the ID of the disk is compared with that stored in the disk unit. If the disk is changed for another 
with the same ID number, and the drive is not re-initialised, the stored BAM will be incorrect. Since the 
ID's are the same, the unit will not recognise that the disk has been changed, and will write data to the 
disk using the wrong BAM. This is clearly likely to lead to the hopeless corruption of some or all of the 
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files on the disk. To avoid any possibility of this depressing occurrence, every disk should be given a 
different ID. 

11.7.2 User files and the BAM: VALIDATE and COLLECT 

The commands VALIDATE and COLLECT tidy up the system files, removing from the BAM any 
blocks which do not belong to any of the files entered in the directory. Since a direct-access or USR file 
has no associated file-name, these commands will free the blocks of such a file, indicating them in the 
BAM as available for use. This can be avoided by writing a routine to reinstate them in the BAM, but 
the simplest procedure is to keep direct-access files on a separate disk, which carries no program or 
sequential files. In general the commands VALIDATE and COLLECT should not be used on disks 
carrying direct-access files. 

Fig 1 1 . 1 shows a schematic plot of the block availability map for a disk which has been NEWed; 
occupied blocks are indicated by an asterisk. Note that only two blocks are occupied - those which 
hold the start of the system file (on track 18). 

Fig 1 1.2 shows the same disk after the DOS support program has been written to it, while Figs 
11.3 and 11.4 show the BAM's for disks which are respectively partially and almost completely filled. 
Note that the tracks closest to that containing the system file are filled first, since this reduces the 
amount of head movement required, and so minimises the access time. 

These figures were obtained using DISKMAP, an invaluable program due to Hampshire. (The 
CBM utility program VIEWBAM performs a similar function.) 

Example 11.9 

100 REM ***************** 

110 REM *R,-'A1A-WRITE V.3* 

120 REM *E.A.FLINN * 

130 REM *NOVEMEER 1981 * 

140 REM ***************** 

150 REM 

160 REM OPEN fl CHANNEL AND RESERVE FIRST AVAILABLE BUFFER 

170 OPEN 1,8, 3.. "#" :REM I.E. CHOOSE ARBITRARV CHANNEL NUMBER EQUAL TO 3 

180 C=3 

190 REM 

200 REM OPEN COMMAND AND ERROR CHANNEL 

210 0PEN15,S,15 

220 REM 

230 A*="THIS IS ENTRY #" 

246 B*="" :FOR 1=0 TO 254 :B*=B*+CHR*C0> :NEXT I 

250 INPUT":>JHICH DRIVE HOLDS DISK " ;D 

260 T=l : INPUT "WHICH TRACK UUU*IIH" :T* :T=VAL':T*> : IF T#="*" THEN GO TO 260 

270 FOR S=0 TO 20 

280 REM ALLOCATE BLOCK 

290 PR I NT# 1 5 , " B- A " ; D ; T ; S 

300 REM SET BUFFER POINTER 

310 PRINT#15,"B-P".:C;1 

320 REM OVER-WRITE BUFFER WITH ZEROES-NOT NECESSARV-USEO HERE FOR CLflRITV 

330 PRINT#1,B* 

340 REM 

350 PRINT#15,"B-P" ;C;1 

360 REM WRITE DATA TO BUFFER 

370 PR I HT# 1 , A*+STR* < S j .: CHR* •', 1 3 > ; 

380 REM WRITE BUFFER CONTENTS TO BLOCK 

390 PR I HT# 15," B-W " ; C ; D .: T ; S 

400 NEXT S 

410 CLOSE 1 

420 CLOSE 15 

430 END 
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WRITING A SIMPLE DIRECT- ACCESS FILE 

Let us consider, first in outline and then in more detail, the sequence of steps which must be carried 
out in order to write a random-access file directly to disk. The complete procedure is illustrated by the 
program of Example 11.9. For ease of understanding, each entry will consist only of a single item, and 
a separate block will be allocated to each entry. 

1) A "channel" must be opened between the PET and the disk controller, and a section of 
memory - a 'buffer' - reserved within the disk controller. The term 'buffer' is used, since the 
use of this temporary store allows data to be input from the PET much faster than it can be 
written to disk. Each buffer consists of 256 bytes of memory - the contents of a block - 
although only 255 of these bytes can be used for data storage. 

2) As in all programmed disk operations, a command channel must be opened between PET 
and disk controller, using a secondary address of 15. 

3) The data or variables to be stored are written into the buffer. This can be done starting at any 
byte in the buffer, from 1 to 255 (byte is reserved by the disk controller to indicate the 
location of the last valid character written into the buffer). The location of the first data 
character written into the buffer is controlled by setting a "buffer pointer". This simply 
specifies the byte within the buffer (from 1 to 255) at which the data will begin. 

4) It is not absolutely essential to update the Block Availability Map to indicate that a specific 
block as been used, but it is a good idea, since an accurate BAM makes it easier to avoid 
over-writing existing data. The BAM is updated using the "block-allocate" instruction. 

5) The data are next copied from the buffer into a specified block on the disk, freeing the buffer 
for re-use. The block is specified by means of the track and sector numbers. 

6) Finally, if all disk operations are complete, the files are closed. 
Let us now consider each of these steps in greater detail. 

1) A channel is opened by a command of the form 

OPENlfn,8,cn,"#" 

lfn, the logical file number, can as usual take any value from 1 to 255 inclusive. 

The primary address - normally 8 - is that of the disk drive unit. The channel number, en 
- the secondary address in the OPEN command - can have any value between and 14. 
Values of and 1 are, however, respectively interpreted as LOAD and SAVE commands, so 
that unless these operations are required, the channel number is restricted to the range 2-14. 
Up to five channels may be open at any one time. 

A typical command to open a buffer would thus be: 

OPENl,8,3,"#" 

This will cause the first available buffer to be allocated to channel number 3, with an 
associated logical file number of 1. 

2) The command and error channel is opened by a simple OPEN instruction, using a secondary 
address of 15: for example 

OPEN15,8,15 

It is a convenient aid to memory here to use a logical file number of 1 5 also. The primary 
address is of course that of the disk drive. 
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3) The data or variables to be stored (only one in this case) are copied into the buffer. They can 
be written into any selected location, but in this case byte 1 will be the first used. 



Figure 11.5 
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The buffer pointer is set via the command and error channel, using the "B-P" or 
"buffer-pointer" command. The syntax of this command is 

PRINT#lfn, "B-P"; en; cp 

Thus, for example, if the logical file number 15 has been allocated to the command and 
error channel, and the channel number is 3, then the buffer pointer will be set to character 
position 1 (cp=l) by the command 

PRINT#15, "B-P"; 3; 1 

NB The syntax of this command may take a number of forms, all perfectly valid (see CBM 
Floppy Disk User Manual). It is however safer to stick to a single form, so as to reduce the 
risk of error. 

4) The data or variables are then written to the buffer from the PET, using the command 

PRINT#lfn, data 

Thus, for instance, if we wish to copy the variable A$ into the buffer originally opened 
by the command 



we use: 



OPEN1, 8, 3, "#" 
PRINT#1,A$ 



This will copy the string variable A$ into the buffer whose channel number is 3. The first 
character of A$ will be written at the location indicated by the buffer pointer, and the 
location of the last valid character will be stored in byte 0. 

Terminators If the simple command above is used, the buffer will contain the string 
A$ followed by a carriage return and a line feed. Either of these on its own is adequate to 
denote the end of the string, and the second of these - the line feed - will therefore be read as 
the first character of any succeeding data. This can clearly cause trouble in some applications 
- e.g. when sorting. To avoid this, the transmission of the carriage return and line feed may 
be suppressed by means of a semicolon . A line feed on its own - CHR$( 1 3) - is then sent, and 
a further semicolon is added to prevent the transmission of a further carriage return and line 
feed. The complete command is then: 

PRINT#1,A$; CHR$(13); 
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5) The data are copied from the buffer into a specified block on the disk by means of the 
"block- write command". On unmodified 2040 and 3040 units, there are two allowable 
forms of this command, "B-W" and "U2". Only the second of these is available on 4040 and 
updated 2040/3040 units. The difference between the two commands is relatively slight. 
When "B-W" is used, the position of the last character written is stored in byte of the block. 
This can, of course, be a serious disadvantage if only a part of the block contents is to be 
rewritten - e.g. when only one field of an entry is to be changed. When U2 is used, the 
contents of byte are not altered, so that this command is more appropriate when a file is to 
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be up-dated, rather than written from scratch. Since "B-W" is not available on 4000-series 
systems, it is in general better to use U2 at all times, as this will make your programs more 
readily transferable between systems. 

As with "B-P" there is a range of permissible syntaxes, but it is advisable to use one 
version consistently. 

The format is 

"B-W"; en; drno; t; s 

or "U2"; en; drno; t; s 
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where cn,drno,t and s are respectively the channel number, the number of the drive 
containing the disk, and the track and sector of the block to which the buffer is to be written. 
Using the channel-number 3, (as assumed in section 1), taking the disk to be in drive 0, and 
assuming that we wish to write to sector 13 of track 5, the appropriate command would then 
be (if the command and error channel has been given the logical file number 15): 

PRINT#15, "B-W"; 3; 0; 5; 13 

or PRINT#15, "U2"; 3; 0; 5; 13) 

Now, bearing these points in mind, study Example 1 1.9 and see how they are applied in practice. 
This program writes into each sector S of some specified track T the message "THIS IS ENTRY #S". 
Since this very simple program expects to find 21 blocks on the track selected, only tracks 1 to 17 can 
be used. Fig 11.6 shows the Block Availability Map for a disk after the program of Example 11.9 has 
been run, using tracks 1 and 5. (The blocks on track 17 contain the DOS support program, while the 
two filled blocks on track 18 contain the disk header -see fig 11.2). The contents of all the 255 data 
bytes in a block may be examined by means of a special program such as SECTORPRINT (The PET 
Revealed by Nick Hampshire). This facility is invaluable when attempting to debug direct-access 
programs. 

If program 11.9 is run without line 330, and the contents of each block are examined using 
SECTORPRINT or some similar program, it will be found in general that in addition to the expected 
message, a number of other characters are stored in the block, outside the region occupied by our 
string variable. When data are written to the buffer, any characters already present from previous 
usage of the buffer (for example, by the disk controller) are over-written; the region not over- written 
however remains unaffected. Then, when the buffer contents are written to disk, this unwanted 

Example 11.10 

100 REM *********** 

110 REM *R,-'A1-READ* 

120 REM *EAF 1982 * 

130 REM *********** 

140 

150 INPUT-'UdHICH DRIVE CONTAINS DISKIUJKNUU" :D* : IF D*="*" THEN 150 

160 D=VHL<D*> 

170 

188 REM OPEN CHANNEL AND RESERVE FIRST AVAILABLE BUFFER 

190 C=5:REM SELECT CHANNEL NUMBER - HERE #5 

200 OPEN 1,8. .5.. "#" 

210 

220 REM OPEN COMMAND AND ERROR CHANNEL >::SA=150 

230 OPEN 15, 3,15 

240 

250 REM SELECT TRACK 

260 T=l :IHPUT"WHICH TRACKUUU*IMI" ;T* :T=VALCT*> : IF T*="*" THEN OOTO 260 

270 

280 REM SELECT ENTRY TO BE READ 

290 PRINT"WHICH FILE ENTRY" ; : I NPUT " IMMWIiil" ?F* : IF F$="*" THEN280 

300 F=VALCF*> 

310 

320 REM READ APPROPRIATE ENTRY INTO BUFFER 

330 PR I NT# 1 5 , " B-R " ; C ; D ; 1 ; F 

340 

350 INPUT#1,E* 

360 PRINT: PR I NTE* : PR I NT 

370 INPUT "FINISH - V OR NgllJYIIII" ; R* 

380 IF LEFT*<:R*,i:J = "N" THEN GOTO 290 

390 CLOSE 1 :CL0SE15 

400 END 
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(though harmless) information is stored also. Line 330 in the demonstration program overwrites such 
unwanted information with zeros, to clarify the process, but this is not necessary in a practical 
program. A print-out of the contents of a block, written using the program of Example 11.9 and read 
by means of SECTORPRINT, is shown in fig 11.7. 

READING A USER FILE 

In general, the process of reading back data from a direct-access file is similar to that of writing a file. 
We must first open a command and error channel, and a channel to a reserved buffer in the disk 
controller. The contents of a specified block are transferred to the buffer using the block-read 
command ("B-R" or "Ul"). The data may then be read from the buffer using INPUT# or GET#. 



601 :THIS IS 54 48 49 53 20 49 53 20 

009:THE FIRS 54 48 45 20 46 49 52 53 

017 :T PART 54 20 50 41 52 54 20 4F 

025 :F ENTRV 46 20 45 4E 54 52 59 20 
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or 



The format of the block-read command is the same as that for block- write: 
"B-R";cn;drno;t;s 

"Ul";cn;drno;t;s 



The difference between the two is that "Ul" forces byte to 255. Thus, every character in the 
buffer can be read using INPUT# or GET#; "B-R" however leaves the position of the last valid 
character in byte so that an INPUT# will terminate when it reaches this character. 

This program demonstrates the process, and allows us to read back the (rather uninteresting) 
messages stored by the previous program. 
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Example 11.11 

108 REM ************ 

110 REM *R/A2-WRITE* 

120 REM *EAF 19S2 * 

130 REM ************ 

140 

150 REM THIS PROGRAM PRINTS TWO VARIABLES INTO EACH BLOCK 

160 

170 0PEN1,S,5,"#" 

180 0PEN15,S., 15 

190 A*="THIS IS THE FIRST PART OF ENTRV #" 

200 B*="THIS IS THE SECOND PART OF ENTRV #" 

210 Z*= FOR 1 = 1 TO 254 :Z*=Z*+CHR*<0>s NEXT I 

220 INPUT"ZWHICH DRIVE HOLDS DISK";D 

230 T=l: INPUT "WHICH TRACK" tT 

240 FOR S=l TO 20 

250 PRINT#15,"B-A".s5.:D;T;S 

260 PRINT#15,"B-P".s5;l 

270 

280 PRINT#1,Z*:REM OVER-WRITE BUFFER WITH ZEROES FOR CLARITV 

285 

298 PRINT#15,"B-P".s5.!l 

300 REM WRITE DATA TO BUFFER 

310 PRINTttl ,A*+STR*<S> ;CHR*< 13> .; 

320 PRINT#15,"B-P";5;101 :REM MOVE TO START OF NEXT FIELD 

330 PR I NT# 1 , B*+STR* < S > ; CHR* < 1 3 > ? 

340 PRINT#15,"B-W";5.sD;Tj!S 

350 NEXT S 

360 CLOSE 1 : CLOSE 15 

370 END 



FILE ENTRIES WITH MORE THAN ONE FIELD 

Where several items of data are to be input for each file entry, we must decide how the available space 
is to be divided between the different data fields. Assuming once more that a single block is allocated 
to each file entry, the available 255 bytes must be divided appropriately. InExample 11.11, two string 
variables are written to disk for each file entry. The first is allocated bytes 1-100, while the second is 
allocated bytes 101-255. As in program 11.9 the buffer is first filled with zeros, in the interests of 
clarity (line 280) . The buffer pointer is set to character position 1 in line 290, and the first string ( A$) is 
written in (line 310). The buffer pointer is set to byte 101 (line 320), and the second string is entered. 
The whole of the buffer is then written into the appropriate block using "B-W" or "Ul" (line 340). 

Fig 11.8 shows the result of running R/A2- WRITE. Provided that the location of each field is known, 
the data may be read out by an essentially similar process, as shown in program 11.12. 

Alternatively, part of each record may be modified as in example 11.13. The result of running this 
program (with a different message) is shown in Fig 11.9. 

NB In these demonstration programs illustrating the construction and use of user files, disk 
error routines have been omitted in the interests of clarity. In a program intended for serious 
application, the disk error channel would of course be checked after every disk operation. 

In general, the availability of later versions of PET BASIC and DOS, which allow the use of 
relative files, has made the user file effectively obsolete. For the owners of earlier machines which 
have not been up-dated, however, the user file is essential wherever a random-access or direct-access 
file is required. The mechanism of creating and accessing a user file is in any case (besides being good 
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for the soul) a valuable study for those interested in the details of the processes by means of which 
computers store data. In the later CBM machines, although the same processes must be carried out, 
this is done by routines built into the software, which are transparent to the user. 

Example 11 .12 

*********** 
♦R/A2-READ* 
*ERF 1982 * 
*********** 

THIS PROGRRM READS TWO STRING VARIABLES FROM EACH BLOCK 

8,5, "#" :REM RESERVE BUFFER - LABEL CHANNEL <#5> 
138 0PEN15,S,15 

218 INPUT "3WHICH DRIVE HOLDS DISK" jD 
228 T=l: INPUT "WHICH TRACK" ;T 
238 REM 

248 REM SELECT ENTRV TO BE READ 
258 INPUT "WHICH FILE ENTRY DO VOU WANT TO SEE".sF 
268 REM 

278 REM READ APPROPRIATE ENTRV INTO BUFFER 
288 PRINT#15,"U1 :";5;D.sT.;F 
298 

388 REM READ AND DISPLAY BUFFER CONTENTS 
318 I NPUT#1, A* SPRINT -.PRINT A* 
328 PRINT#15,"B-P";5;181 
338 I NPUT#1,B* sPRINT : PR I NT B* 
348 INPUT-IFINISH - V OR N|||Mllt";R« 
358 IF LEFT*<R*,1>="N" THEN GOTO 258 
368 CLOSE1 sCLOSElS 
378 END 



Example 11.13 

188 REM ************* 

118 REM *R/A2-M0DIFV* 

128 REM *EAF 1982 * 

138 REM ************* 

148 

158 REM THIS PROGRAM UPDATES THE SECOND FIELD IN EACH BLOCK 

168 

170 0PEN1,8,5,"#" 

188 OPEN 15, 8, 15 

218 INPUT "3WHICH DRIVE HOLDS DISK".:D 

228 T= Is INPUT "WHICH TRACK "rT 

225 INPUT "HEW E"NTRV" ;A* 

230 FOR S=l TO 28 

240 PR I NT# 15," B-R " .: 5 .: D .: T .: S 

250 PR I NT# 15," B-P " .; 5 .: 1 8 1 

268 PR I NT# 1 , A* .: CHR* < 1 3 > .; 

290 PR I NT# 1 5 , " B- W " ; 5 .: D .! T r S 

300 NEXT S 

310 CLOSE 1 s CLOSE 15 

328 END 



CHAPTER 12 

Making Programs Crash-Proof 
and Friendly 
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Making Programs Crash- 
Proof and Friendly 



Many computer programs - including expensive commercial packages - make no allowance for the 
fact that the user may well be someone with little or no technical knowledge, and no familiarity with 
computers. Thus, for instance, in word-processor packages the user - normally a typist with no 
computer background - is typically called on to remember a long list of arbitrary symbols before he or 
she can make use of the various facilities offered by these otherwise excellent programs. There is no 
excuse for this, and anyone designing programs or packages for general use should devote consider- 
able effort to making them as "user-friendly" as possible. 

With this end in view, the programmer should ensure that at all stages the prompts offered to the 
user are intelligible and helpful, and that the display itself is well laid-out, and easy to read and 
understand. Computer jargon should be avoided in the instructions and prompt messages. These 
should be written in good plain English and suitable for translation if used abroad. Moreover, where 
input is required from the user the program should be carefully structured, first to minimise the risk of 
an incorrect input, and then to ensure that a faulty input does not cause the program to fail. 

A little thought at the design stage can save a great deal of subsequent ill-feeling and wasted time. 
Any program which "crashes" frequently, especially if this occurs after the user has already devoted 
considerable time to inputting data, will rapidly become very unpopular, and bring down considerable 
abuse upon the head of its designer. The programmer should therefore always strive to produce 
'robust' programs. Robustness can be improved by the use of a few simple techniques, together with 
forethought and common sense. 

Various common errors or misunderstandings on the part of the user may occur: 

1) The user may return alpha-numeric data where the program requires a numeric input (e.g. 
"TEN" instead of "10"). This will cause the rather misleading message "REDO FROM 
START" to be output, striking terror into the heart of the inexpert. To avoid this difficulty 
ALL inputs should be read in as strings, regardless of whether the input data required are 
numeric or alpha-numeric (i.e. text). 

Once inside the machine, the input string can be dissected and inspected, using the 
techniques described in chapter 4. Where a numerical input is required by the program, the 
numerical value of the string can be extracted by means of the VAL function. Some care is 
necessary in this case, however, since the function VAL will return a value of zero in several 
cases where no valid numerical symbol has been input. This will occur wherever the first 
non-blank character of the string is not a numeric digit. 

Thus for example, the commands 

N = VAL("0") 

N = VAL("0AB2D7") 

N = VAL("TEN") 

will all result in a value of zero being assigned to the variable N. 
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Where zero is not a permitted value for N this will of course cause no difficulty. 
Otherwise, when a value of zero is returned, we must check the first character of the string, 
using the LEFT$ function. 

2) The operator may accidentally have entered a valid but incorrect input. To check this, he 
should be given an opportunity to confirm the correctness of the input before it is fed into the 
program. This may be done immediately subsequent to each data entry, as in the demonstra- 
tion program which follows. Alternatively, all the input data may be presented as a block, so 
that the user can alter any incorrect items. This necessitates a more complex program 
however. 

3) If the operator accidentally or mischievously responds to a request for input data by pressing 
the RETURN key without pressing any other, execution of the program will be instantly 
terminated, and the PET will return to immediate mode. This may cause considerable 
inconvenience if the user has already worked part-way through a lengthy program. This can 
be avoided by inputting data via a logical file. A file is opened to the keyboard. Input data are 
then transferred to the logical file inside the machine, rather than being returned to the 
program, and a null entry will no longer cause the program to crash. This technique is seen in 
the input subroutine which starts at line 1 920 of program example 1 2 . 1 . A simple alternative 
method of avoiding null inputs, due originally to Hampshire, is demonstrated in program 
12.2. This input routine can easily be defeated by a sufficiently malevolent or incompetent 
user, but it is very useful in programs where the highest degree of robustness is not essential. 

4) Before an input is used in the program, it should be checked for validity - is it too large, too 
small, the wrong data type? If so, an appropriate message may be displayed, pointing out the 
error and requesting the user to supply more appropriate data. (See for example, lines 1520, 
2000 and 2080 of program 12.1.) 

5) If the RUN/STOP key is accidentally pressed while a program is running, the program will 
terminate. This may be prevented by disabling the stop key at the start of the program. 
However, the user should be offered from time to time an opportunity to terminate the 
program without turning off the machine. 

On 3000 and 4000 series PET's the RUN/STOP key is controlled by the contents of 
memory location 144. (This location normally contains the decimal number 46 on 3000- 
series, and 85 on 4000-series machines.) 

The key may be disabled by POKEing 49 or 88 respectively into this memory location, 
but DON'T forget to re-enable the STOP key at the end of your program. (See lines 1250 and 
1880). 

Where a Superchip or similar extension ROM is in use, the normal contents of location 
144 are altered, and the operation of the machine will be disrupted if the program crashes 
while this location contains 49 (or 88). In this case, the machine must be turned off and on 
again to restore normal operation. This may be avoided by turning off the Superchip under 
program control at the start of the program. If this is not done, the initial contents of location 
144 should be PEEKed and saved for restoration at the end of the program. 

The demonstration program ELAMBDA listed below offers examples of the techniques 
described here, together with a demonstration of some of the facilities offered by the PET 
printer. The actual function of the program, which is somewhat technical, is unimportant; 
the program is used here simply as a vehicle to demonstrate useful techniques for interactive 
programs. 
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Example 12.1 



*ELAMBDA V5.4 ' * 

*fl DEMONSTRATION PROGRAM TO ILLUSTRATE DESIRABLE FEATURES FOR* 
* INTERACTIVE PROGRAMS * 

*E.fl.FLINN APRIL 1982 * 

♦Hi********************************************************** 

THIS PROGRAM ALLOWS THE USER TO CHANGE AN INCORRECT INPUT 

IT IS ALSO FULLV COMMENTED 

OPEN PRINTER CHANNEL FOR TRANSMISSION OF DATA TO BE FORMATTED 

OPEN CHANNEL FOR TRANSMISSION OF FORMATTING DATA 

OPEN CHANNEL TO SCREEN CAS DEMONSTRATION ONLV) 

OPEN CHANNEL FOR PRINTING OF UNFORMATTED DATA 

OPEN CHANNEL TO SET LINE SPACING 

SET LINE SPACING 



1000 REM 

1010 REM 

1020 REM 

1030 REM 

1040 REM 

1050 REM 

1060 REM 

1070 REM 

1080 REM 

1090 REM 

1100 REM 

1110 REM 

1120 0PEN1..4, 1 

1130 REM 

1140 0PEN2..4..2 

1150 REM 

1160 OPENS, 3 

1170 REM 

1188 GPEN4..4 

1190 REM 

1200 0PEN6,4,6 

1210 REM 

1220 PRINT#4 

1 230 PR I NT#6 .. CHRf < 36 ) 

1240 REM DISABLE STOP KEV 

1250 POKE 144, PEEK CI 44 ;■ +3 

1260 PRINT'T]" 

1270 PRINT#3 

1280 PRINT#3 

1290 PRINT#3," ELECTRON WAVELENGTHS" 

1300 PRINT#3," ******** ***********" 

1310 PRINT#3 

1320 PRINT#3 

1330 L*=" LOWEST ENERGV IN ELECTRON-VOLTS" 

1340 PRINT#3,L*.:"? ".: 

1350 GOSUB 1920 

1360 IF RJi=l THEN GOTO 1310 

1370 L=A 

1380 H$= "HIGHEST ENERGV IN ELECTRON-VOLTS" 

1390 PRINT#3, "3" 

1480 PRINT#3 

1410 PRINT#3 

1420 PRINT#3,L*.;" = ";L 

1430 PRINT#3 

1440 PRINT#3 

1450 PRINT#3,H*.;"? ".: 

1460 GOSUB 1920 

1470 IF RX THEN GOTO 1380 

1480 H=A 

1490 IF L=<H THEN GOTO 1560 

1590 PRINT 

1510 PRINT 

1520 PR I NT "PLEASE DON'T BE SILLV!" 

1530 FOR 1=1 TO 2090: NEXT I 

1540 PR I NT "3" 

1550 GOTO 1310 

1560 S*="STEP SIZE IN ELECTRON-VOLTS" 

1570 PRINT#3, "T 

1580 PRINT#3 

1590 PRINT#3 

1600 PRINT#3,L*,'" = ";L 

1610 PRINT#3 

1620 PRINT#3 

1630 PRINT#3,H*J"=";H 

1640 PRINT#3 

1650 PRINT#3 



144 GETTING MORE FROM YOUR PET/CBM 

1660 PRINT#3,S*;"? ".: 

1676 GOSUB 1920 

1680 IF R'/. THEN GOTO 1560 

1690 S=A 

1 780 PR I NT#4 , " ENERGV < ELECTRON-VOLTS ) WAVELENGTH < ANGSTROMS > " 

1710 PRINT#4 

1720 REM TRANSMIT FORMATTING DATA 

1730 PRINT#2.. " 999999 ZZ.99 

1740 K=12.1833 

1750 FOR V=L TO H STEP S 

176© LA = c:iHT<a00*K/SQR<V>>+0.5>>/100 

1770 REM TRANSMIT DATA FOR FORMATTING 

1730 PRINT#1,V,LA 

1790 NEXT V 

1800 REM RESET LINE SPACING 

1810 PR I NT#6 , CHR* < 24 > = PR I NT#4 

1820 CLOSE 1 

1330 CL0SE2 

1840 CL0SE3 

1850 CL0SE4 

I860 CLOSES 

1870 REM RE-ENABLE STOP KEV 

1330 POKE 144, PEEK (1 44 ) -3 

1890 END 

1900 REM INPUT SUBROUTINE 

1910 REM ***** ********** 

1920 R'i=0 

1930 REM OPEN INPUT CHANNEL TO KEYBOARD 

1940 OPENS, 

1950 REM INPUT VARIABLE AS STRING 

I960 INPUT#5,A$ 

1970 REM CHECK FOR HULL INPUT 

1930 IF m="" THEN RY.=l 

1990 REM CHECK FOR NON-NUMERIC INPUT OR OUT-OF-RANGE VALUES 

2000 Wl*=" INPUT MUST BE A FINITE POSITIVE NUMBER, EXPRESSED IN FIGURES" 

2010 IF VflL<A$»0 THEN GOTO 2070 

2920 PR I NT " 3" : PR I NT : PR INT: pr i NT 

2030 PRINT Wl* 

2040 FOR J=l TO 2000 : NEXT J 

2050 R.-i=l 

2060 GOTO 2220 

2070 IF VflL<fl*»0.1 AND VALCAfXlES THEN GOTO 2120 

W2*=" NUMBER MUST BE GREATER THAN 0.1 AND LESS THAN 1000000" 
2090 PR I NT " n" : PR I NT : PR I NT : PR I NT 
2100 PRINTW2* 
2110 GOTO 2040 
2120 PRINTS PRINT -PRINT 
2130 PRINT TAB<18> VAL<A*> 
2140 PRINT: PRINT 

2150 PRINT" IS THAT CORRECT? PLEASE TVPE V FOR VES, N FOR NO 
2160 PRINT PRINT 
2170 INPUT#5,B* 
2130 IF LEFT*t'B$, 1)="V" THEN GOTO 2210 

2190 RK=1 

2200 REM EXTRACT VALUE OF VARIABLE FROM INPUT STRING 

2210 fi=VAL<A*:> 
2220 CLOSES 
2230 RETURN 



The program in fact produces a table of electron wavelengths corresponding to specified energies 
(don't worry about this if you don't understand it). 

The user is asked to specify the lowest and highest energies of interest, and the interval between 
successive entries in the table. Once this information has been satisfactorily input, the wavelengths are 
calculated and printed out on the PET printer, using the built-in formatting facility. 
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The interest of the program, so far as we are concerned, lies in the techniques used to input the 
numbers required. Any invalid entry is rejected and the user is given a fresh opportunity to enter valid 
data. Once a valid input has been received, the user is given a chance to alter it before the program 
proceeds to the next step. The program starts by opening a number of channels to the printer (lines 
1 120 to 1200), so that the line spacing can be reset for improved legibility and the formatting facilities 
can be utilised. A channel is opened to the screen also to show that this can be done; it serves no other 
purpose in this program, although this facility is quite useful under some circumstances. The stop key 
is disabled (line 1250) and a title is displayed on the screen. 

The user is then requested to input a value for the lowest energy in the table (line 1340). (Note 
that this prompt is produced by means of a PRINT statement, rather than an INPUT statement.) The 
program then jumps (line 1350) to the input subroutine (line 1920). This subroutine contains a 
number of points of interest. 

First of all, the 'flag' variable R% is set to zero. So long as the user's input satisfies all the checks 
which follow as part of the subroutine, R% will remain zero, but should the input fail any of the checks, 
R% is set to 1 . This is detected by the main program when we return from the input subroutine, and the 
appropriate prompt message is repeated. The input is read in as a string variable, A$, via a logical file 
which opens a channel to the keyboard. This ensures that the program will not crash if the RETURN 
key is pressed before an input has been entered. Should this occur, R% is duly set to 1 (line 2050) so 
that the prompt message will be repeated on returning to the main program. 

The value of the number is extracted from the string A$ and checked to ensure that it is positive 
(line 2010). If not, an error message is displayed for a short period (lines 2030 and 2040) before the 
original prompt is repeated. The magnitude of the number is checked next (line 2070), to see that it 
lies within the specified limits (here 0.1 to 1,000,000). If not, a suitable error message is again 
displayed (line 2100) and R% is set to 1, so that the original prompt will be repeated. 

Finally, if the number passes all these tests, it is displayed on the screen, and the user is given an 
opportunity to alter it (lines 2130-2180). If the user confirms that it is acceptable, the number is 
assigned as the value of the variable A, the input file is closed and we return to the main program, 
where the value of A is assigned to the appropriate variable - L, H or S. If the user rejects the input, 
the flag R% is set to 1, indicating an unacceptable input, and the original prompt is displayed once 
more, allowing the user to input a new number. 

This process is repeated until a satisfactory set of numbers has been entered. The program checks 
(line 1490) to see that a humorous user does not enter an upper limit H which is higher than the lower 
limit L. However, the step size S is allowed to have any value between 0. 1 and 1 ,000,000, regardless of 
the values of L and H. Even if S is greater than H, the program will run correctly, printing out a single 
entry which corresponds to the lower limit L. The wavelengths corresponding to the specified range of 
energies are then calculated and printed out (lines 1750-1790). The line spacing is reset to the 
standard value (line 1 8 1 0) , the various logical files are closed, and the RUN/STOP key is re-enabled - 
most important. 

Note that line 1810 contains a plain unformatted PRINT# statement. This avoids problems if the 
program is run several times in succession. If more than one PRINT# statement with a secondary 
address of 6 is used in succession to alter the line spacing, it will be found that only the first such 
statement is obeyed. Just as in the case of the formatting facility (secondary address 2), instructions to 
alter the line spacing must be separated by ordinary unformatted PRINT# statements to overcome 
this bug - hence the second part of line 1810. (Try the effect of removing the PRINT#4 statement in 
line 1810 and running the program several times in succession.) 

Program 12.2 demonstrates the simple alternative input routine mentioned earlier. The prob- 
lems resulting from a null entry are avoided by ensuring that a valid character (here an asterisk) is 
always input, even when the user presses RETURN without making an entry. Although this routine is 
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not completely fool-proof, it is quick and easy to program, and has been used in several of the 
demonstration programs elsewhere in this book. Where a yes/no (Y/N) response is required, a "Y" 
(or an "N") can be entered as the default string, rather than an asterisk. In this case line 1 90 of course 
becomes superfluous. 



100 
110 
120 

130 
140 
156 
160 
170 
180 
190 

200 

210 
220 
230 
240 
250 
2f& 
270 
280 
290 

300 



REM AN ALTERNATIVE INPUT ROUTINE 

REM ** *********** ***** ******* 

PRINT"."]" 

REM 

IHPUT">M»IMI";h* 

REM 

REM THIS SHIFTS THE CURSOR THREE SPACES TO THE RIGHT, THEN PRINTS AN 

REM ASTERISK AND SHIFTS THE CURSOR THREE SPACES LEFT AGAIN 

REM 

IF A*="*" THEN PR I NT "H";: GO TO 140 

REM 

REM IF NOTHING HAS BEEN INPUT, A$ IS SIMPLV EQUAL TO "*" 

REM THE INPUT PROMPT IS THEREFORE REPEATED IN THE SAME SCREEN LOCATION 

REM 

PR INT" :cM»liii»»l" fl* 



REM THIS ROUTINE CAN IF REQUIRED BE MODIFIED SO AS TO GIVE fl 
REM ...DEFAULT REPLV TO THE PROMPT, BV PRINTING, FOR EXAMPLE, 
REM ..."N" RATHER THAN "*" 



.■'ALID. 



CHAPTER 1 3 

The PET/CBM In Control Applications 
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The PET/CBM In 
Control Applications 



Most users think of desk-top computers simply as devices for handling data but in fact many hundreds 
of small computers like the PET are in daily use in industry, controlling and monitoring manufacturing 
processes or supervising testing procedures. 

13.1 MICROPROCESSOR SYSTEM ARCHITECTURE 

Before proceeding further it will be helpful to consider the basic layout or "architecture" of a 
microprocessor system, as shown schematically in Figure 13.1. 



Figure 13.1 
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It will be seen that the microprocessor chip or MPU - the 6502 in the case of the PET/CBM - 
communicates with the memory and with any input/output devices by means of three main "data 
highways" or "buses". These are groups of parallel conductors along which digital signals may pass in 
either direction. 

Most of the microprocessors currently in widespread use, like the 6502, have a data bus 
consisting of eight parallel conductors. Eight binary digits or "bits" of information - one byte - may 
therefore be sent simultaneously along the data bus. 

Similarly, almost all of these "eight-bit" microprocessors have an address bus consisting of 
sixteen parallel conductors, so that sixteen bits of information can simultaneously be sent out on this 
bus. This information, of course, is sent in the form of electrical signals which are decoded to give an 
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"address'. This address specifies the precise location in memory from which data is to be read, or to 
which it is to be sent. Given sixteen bits, each of which can take on a value of either or 1, there are 
65,536 different and distinct addresses which can be sent out on the address bus. (This number is 
actually referred to as 64K in computer j argon; 1 Kbyte = 2 10 or 1 ,024 bytes.) The microprocessor can 
thus make use of memory up to a total capacity of 65,536 bytes of information, which is sufficient to 
store 65,536 alpha-numeric characters. 

13.2 MEMORY-MAPPED INPUT/OUTPUT 

In practice, it is relatively rare for a microcomputer to make use of all the available memory space, so 
that a large number of the possible memory addresses are in fact unused. This means that those 
combinations of address bits which do not refer to one of the memory locations actually in use can be 
decoded and used to activate specific input or output devices. Where this is done, so that the 
input/output devices occupy locations in the machine's "memory map" or "memory space", the 
system is said to use "memory-mapped input/output". Clearly, any microprocessor can use 
memory-mapped I/O, although some microprocessors (not the 6502) also have additional input- 
output facilities which allow the full 64K of memory to be used at the same time as a useful number of 
input/output devices. 

The control bus in the microprocessor system carries the instructions sent out from the MPU to 
tell the other elements of the system precisely what is required. For example, if we wish to read a byte 
of information from a specific memory location, the appropriate address is sent out on the address bus 
and a "read" signal is sent out along the control bus. This causes the byte of data stored at the specified 
memory location to be sent out from the memory on the data bus in order that it can be read by the 
MPU. Similarly the MPU may send out a byte of data to be written into a specified memory location, a 
"write" signal being sent out on the control bus in this case, along with the appropriate address on the 
address bus. 

In the PET, since memory-mapped I/O is used, it is possible to address an input or output device 
as if it were a portion of memory, data being written to or read from it in exactly the same way. 

Essentially, therefore all input/output operations on the PET are identical with normal memory 
read/write operations. Although we can handle peripheral devices in just the same way as memory, 
PEEKing data from them, and POKEing data into them, we can, in some cases, make use of routines 
already present in the operating system of the PET which greatly simplify the process. We can input 
data from the keyboard and display it on the screen, or save it on disk or tape, without having to 
specify each step of the process in detail. In some control applications such as those which use the 
IEEE- 488 interface this is true also, but in general we shall see that the programs for input/output 
applications must deal with data transfer in a very basic way. 

13.3 PET I/O INTERFACES 

There are three different physical routes by which the PET can interact with external machines or 
instruments, other than the cassette deck; access to these is via edge connectors as shown in figure 
13.2. 

13.3.1 The IEEE- 488 interface 

This is routinely used to communicate with standard PET/CBM peripherals such as the printer or disk 
unit. The IEEE-488 bus system was initially devised for use in control and instrumentation applica- 
tions however, so that the PET can very easily be used to monitor or control other instruments such as 
thermometers, digital voltmeters etc, if they are equipped with this industry-standard interface. The 
PET is in fact almost unique among desk-top computers in this respect, since on most machines the 
IEEE-488 interface is an expensive and often inconvenient extra, whereas with the PET it is standard 
equipment. 
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Figure 13.2 
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The PET operating system also contains a number of routines which greatly simplify the use of 
the IEEE-488 port from the programmer's view point. 

Where the microcomputer must interact with devices not already equipped with an IEEE-488 
interface, the construction of suitable interface circuits may be quite complex, so that the IEEE-488 
port is not likely to be used under such circumstances. 

13.3.2 The memory expansion port 

Access to this is by means of a connector inside the machine. Since this port gives direct access to the 
control, data and address buses of the PET, and hence to the 6502 microprocessor which is the heart 
of the PET, this is a very flexible interface, allowing the PET to control processes or systems of 
considerable complexity. By the same token, however, it is equally possible to disrupt the operation of 
the PET, or to do major damage to its internal circuits if something goes wrong, and this port should be 
regarded as being strictly for the expert. 

13.3.3 The user port 

This is relatively easy to use, and like the IEEE-488 port interposes additional electronics between the 
main circuitry of the PET and the outside world. This makes it improbable that any serious damage 
can be done to the PET, although it is still possible that the special interface chip which controls the 
user port may be damaged by carelessness. The user port is the most likely of the PET's three main 
input/output ports to be of interest to the average user. 

The PET user port is controlled by a special interface chip - the 6522 VIA, or Versatile Interface 
Adaptor. The 6522 carries out a number of functions and in fact is of comparable complexity to the 
6502 microprocessor chip itself, having a total of 16 separately addressable registers. (A register is a 
store, capable of holding a binary number. In current microcomputers, most registers can hold an 
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eight-bit number.) The 6522 is connected to the address bus of the microcomputer in such a way that 
these registers occupy memory locations 59456-59471 inclusive. Quite apart from controlling the 
user port, the 6522 also carries out a number of other functions vital to the routine operation of the 
PET. Not all the registers are of interest in connection with the user port, therefore, and only those 
addresses considered to be of relevance are listed in Table 13.1. 



59457 ($E841) 

59459 ($E843) 

59464 ($E848) 

59466 ($E84A) 

59467 ($E84B) 

59468 ($E84C) 

59469 ($E84D) 
59471 ($E84F) 



Port A data register (input/output) 

with handshake 

Port A data direction register (DDR) 

Timer 2 counter register 

(low-order byte) 

Shift register (SR) 

Auxiliary control Register (ACR) 

Peripheral control Register (PCR) 

Interrupt Flag Register (IFR) 

Port A data register - no handshake 



Table 13.1 
User port addresses 

The significance of each of these registers will be explained in turn. 

The user port is brought out to an edge connector, accessible from the rear of the PET (see figure 
13.3). This connector is double-sided, and the user port connections are confined to the lower face of 
the connector. The connections on the upper face are intended primarily for diagnostic use in repair 
and maintenance, and should be left severely alone by any but the most knowledgeable user. A 
suitable socket to fit this edge connector is available from most CBM dealers. 

Figure 13.3 User port connections as viewed from rear of PET 
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ABCDEFHJKLMN 

Digital ground CM PA0 PA4 PA2 PA3 PA4 PAS PA6 PA7 CB2 Digital ground 

Pins A and N are return or "ground" connections for digital signals. Pins PA0-PA7 (C-L) are 
digital signal lines, each capable of carrying one bit of information at a time into or out of the PET 
(note that they are numbered from to 7, rather than from 1 to 8; this is typical of computer usage). 
Pins CA1 and CB2 (B and M) are "handshake lines" or "control lines". Their prime function is to 
indicate either to the PET or to the external circuitry that a correct set of signals is present on 
PA0-PA7, and can now be read into or out of the computer. CB2 also has other functions, the most 
notable of which is probably its ability to generate audio signals, as demonstrated in numerous 
amusement arcade games. 

The nomenclature PAO, PA1, CA1, CB2 and so on, may seem peculiar. In fact, the 6522 actually 
has two data "ports", Port A and Port B, each consisting of eight data lines, with one input control line 
CI and one output control line C2. Not all these connections are brought out to the user port, so that 
lines PB0-PB7, CA2 and CB1 are not accessible. 

NB Since the 6522 plays an important part in the internal workings of the PET, care should be 
taken when POKEing numbers into its registers. If an incorrect address is used, so that the 
number is written into the wrong register, the PET may refuse to respond to any further 
instructions. No permanent harm will result, but it can be very irritating to have to switch 
off the machine and start reloading your program from the beginning again. 
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13.4 DEMONSTRATION HARDWARE: DATA INPUT AND OUTPUT 

Special-purpose demonstration kits which clearly illustrate the operation of the user port can be 
obtained (for example, from A.R.B. Associates), and these are excellent if you can afford them. To 
start with, however, something cheaper may be considered adequate, and this can readily be con- 
structed by anyone with a modicum of electronic experience. 

Let us look first at a single data line, which can be set to act either as an input or an output line. 
When it is used as an input, we must be able to feed in either a logical or a logical 1 ; when it acts as an 
output, we wish to know whether the bit sent out is a or a 1 . 

In digital logic circuits, binary digits are indicated by different voltage levels. With the type of 
logic chips used in the PET, 5V indicates a one, and OV a zero. We must therefore be able to input 
either 5 V or OV to a selected line on the user port; we must also be able to see whether a line is carrying 
a one or a zero, when it acts as either output or input. This is most easily done by means of a 
light-emitting diode or LED. 

Fortunately, a stabilised 5 V supply is readily available at the cassette interface, (see figure 13.4) . 
Figure 13.4 Cassette port connections as viewed from rear of PET. 

\ 2 3 4 5 6 



A B C D E F 

On this connector, corresponding upper and lower pins such as pin A and pin 1 are electrically 
connected. A 5-V supply is readily taken from the two pins nearest the side face of the PET. (A and B 
or 1 and 2.) 

WARNING: Pins 3 and C carry a 6-V unstabilised supply, and it is fatally easy to short this 
supply to the adjacent signal input pins D and 4, damaging the interface chip and 
rendering the cassette interface instantly unusable for loading programs. To avoid 
this, make sure that the power is off before connecting or disconnecting sockets at 
this edge connector. This risk is especially serious if you use any socket other than 
the rather expensive CBM product, so that it is worth tolerating the inconvenience 
of being unable to load or save programs on tape when you are drawing power 
from the cassette port, rather than trying to change plugs with the power on. 



Figure 13.5 Data input circuit 
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The simple circuit of Figure 13.5 allows either a (S2 closed) or a 1 (S2 open) to be fed to one of 
the data or control lines when that line is used as an input. When the line is to be used as an output, SI 
allows the data input circuit to be disconnected from the line. 

Data indicator 

Whether a user port line is being used for input or output, it is useful to have some visual indication of 
whether it carries a logical 1 or a 0. This is most conveniently done using a TTL inverter or inverting 
buffer, and any suitable LED. 



Figure 13.6 Data indicator 
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The inverter may be one section of a 7404, a TTL chip which carries six identical inverters. A 
7404 can therefore be used to drive up to six LED's. 

The complete input/indicator circuit for one line of the port then becomes 



Figure 13.7 Complete input/indicator circuit 
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This may be multiplied if necessary (finances permitting) to give simultaneous indication and 
control on all ten of the port's lines. Care must be taken not to overload the 5- V cassette power supply, 
and it may be found advisable to increase the values of the resistors in series with the LED's to 33011, if 
ten such circuits - the maximum possible number - are to be used at once. 
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13.5 DATA INPUT/OUTPUT 

13.5.1 The Data Direction Register 

Each of the eight data lines PAO to PA7 can be individually programmed to act either as an output or 
an input and furthermore can, if necessary, be repeatedly reprogrammed during the course of a 
program, so that signals can pass freely in either direction through the port. This programming is 
carried out by means of the data direction register (DDR). The DDR is essentially an 8-bit latch in 
which a one-byte number can be stored. (A latch is a circuit in which a binary number can be stored 
indefinitely). Each bit of the DDR corresponds to a specific data line. 

If a specific bit in the DDR is set to 1, the corresponding data line will act as an output. If a bit is 
"reset", to 0, the corresponding data line will function as an input. 

The DDR has the address 59459 (or $E843) in the PET's memory space, and the status of all the 
lines is simultaneously set by POKEing the appropriate number into this address. 

Thus: 

POKE59459,255 

will cause each data line to act as an output, since 255 = 11111111 in binary. 

Similarly, 

POKE59459,0 
will cause each data line to act as an input. 

POKE59459,170 
or 

POKE59459,85 

will cause alternate data lines to act as outputs, with the intervening lines acting as inputs, and so on. 
Note that bit is the least significant bit - the extreme right-hand one - while bit 7 is the most 
significant (left-hand) bit. 

13.5.2 The Data Register 

Data to be sent out from the PET via the user port, or which has been input through the user port, is 
stored in two registers within the 6522 VIA. However, for all practical purposes these may be 
regarded as a single one-byte register, the Data Register or "DR", located at memory location 59471 
($E84F) . A binary number may be POKEd into this location, and the DDR will ensure that only those 
bits corresponding to pins designated as outputs will be fed through to the appropriate pins of the user 
port. If location 5947 1 is PEEKed, the resulting number indicates the values of all the bits present on 
the user port pins, regardless of whether a particular pin is set to input or output. If the signals fed to 
the input pins change, the value of PEEK(59471) will change also. We may therefore determine 
whether any individual input pin is high or low by inspecting the corresponding bit of the one-byte 
number read from memory location 59471. 

13.5.3 Simple input and output routines 

Although we have so far seen only a small part of the user port's facilities, we are now in a position to 
write programs which will allow the user to carry out straightforward input and output. The same 
principles can also be put to good use in the control of simple experiments or models. 

Program 13.1 sets all the user port pins to act as outputs. A number from to 255, input from the 
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keyboard, is then output in binary form via the user port, setting each line of the user port high or low 
according to the value of the number input. 

The program is easily modified to output the numbers from to 255 in order, with a slight delay 
between numbers: the output lines then count up from to 11111111 in binary (Example 13.2). 

Example 13.1 

lflB REM *************** 

11R REM *SIMPLE OUTPUT* 

126 REM *EflF 1982 * 

138 REM *************** 

14R 

150 PRINT"n««flDOH-T FORGET TO OPEN THE DATA ISOLATION SWITCHES" 

1?S pfiKE53459,255:REM SET ALL USER PORT LIHES TO OUTPUT 
ISO IHPUT":«STVPE IN fl NUMBER < 0-255 >".: N 
190 P0KE59471..N 
200 GOTO 180 



Example 13.2 

lee REM ***************** 

110 REM *BINARV COUNTING* 

120 REM *EflF 1982 * 

130 REM ***************** 

140 

150 PR I NT "DON'T FORGET TO ISOLATE DATA SWITCHES" 

160 

170 PQKE59459,255:REM SET ALL DATA LINES TO OUTPUT 

ISO FOR J=l TO 255 

190 P0KE59471.-J:REM OUTPUT NUMBER J TO USERPORT 

200 FOR K=0 TO 50:NEXT K:REM DELAV 

210 NEXT J 

220 GOTO 180 

The program of example 13.3 sets the four high-order bits of the user port to input, and the four 
low-order bits to output. The number input on the four high-order lines is shifted four places (i.e. 
divided by 16), and after a delay is output on the four low-order lines. 

Example 13.3 

100 REM ************** 

110 REM * INPUT/OUTPUT* 

120 REM *EAF 1982 * 

130 REM ************** 

140 

150 PRINT"30PEN 4 LOW-ORDER ISOLATING SWITCHES : CLOSE 4 HIGH-ORDER SWITCHES" 

160 PRINVSMTHE VALUES OF THE 4 HIGH-ORDER DATA SWITCHES ARE REFLECTED"; 

170 PRINT" AFTER A DELAV BV THE 4 LOW-ORDER LEO'S" 

1 80 

190 P0KE59459. 15:REM 4 LOW BITS OUTPUT : 4 HIGH BITS INPUT 

200 H"i=PEEK •:: 5947 1 > 

210 H1";=N"C AND 240: REM CLEAR 4 LOW-ORDER BITS 

220 FOR J=l TO 250: NEXT J: REM DELAV 

230 P0KE59471 r Nl":,-'16:REM SHIFT 4 PLACES RIGHT AND OUTPUT 

240 GOTO 200 
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Program 13.4 sets all the lines to input, and displays on the screen the decimal value of the binary 
number fed in via the pins of the user port. (Note that if an input pin is left disconnected, the PET will 
respond as if a 1 had been input on that line.) 

Example 13.4 

180 REM *************** 

118 REM * INPUT DISPLflV* 

120 REM *EflF 1982 * 

138 REM *************** 

140 

150 PRINT"3fflBP0N'T FORGET TO CLOSE THE DATA ISOLATION SWITCHES" 

160 

178 POKE59459,0:REM SET ALL USER PORT LINES TO INPUT 

ISO 

190 PR I NT "SET THE DATA SWITCHES AND THEN PRESS ANV KEV" 

20O GET A*: IF A*="" THEN GOTO 286 

210 N=PEEK<59471> :REM READ INPUT 

220 PRINT"SHH="N 

230 GOTO 190 

13.6 MASKING 

In control applications it is often necessary to determine whether a specific input line is high or low 
(e.g. whether a switch, thermostat, relay, etc. is open or closed). Some microprocessors have facilities 
for checking or altering individual bits of a one-byte number or "word", but unfortunately these are 
not available on the PET's 6502 microprocessor. To determine or alter the value of a single bit read in 
from the user port it is therefore necessary to use a technique known as "masking". Masking relies on 
the use of the logical operations AND and OR, and while it would not be appropriate here to launch 
into a lengthy explanation of Boolean algebra, it is necessary to look a little more closely at these 
logical operations. 

Without going into the origin of the terms, we can define the basic logical operations by means of 
"truth tables". In what follows a, b and c are logical variables, each of which can take only the values 
or 1. 

AND 

If a = 1 and b = 1, a AND b = 1 

If either a = or b = or both, a AND b = 

Writing this in the form of a truth table, we have, putting c = a AND b, the following result. 



a ANDb 



OR 

lieither a or b, or both, is equal to 1 then a OR b = 1. If both a and b are zero, a OR b = 0. 



a 


b 


c 
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Although strictly speaking the logical operations described above are valid only for one-bit 
numbers, the same terms are used in the microprocessor world to describe the process of carrying out 
the operation bit-by-bit on all the bits in two binary numbers of the same length. 

Thus 

00001 1 1 1 
AND 110 011 



0000001 1 

Only in bit positions and 1 are the bits of both numbers equal to 1, so only bits and 1 of the 
result will be equal to 1 . 

We can select out a single bit of a number by ANDing the number with a "mask" containing only 
a single 1: 

1011X01 1 
AND 10 



0000X000 



Here every bit except that indicated by X will be cleared to a 0; the value of that bit will be 
unaltered. 

We may similarly clear a specified bit - i.e. reset it to 0. For instance, if we wish to reset bit of a 
number to a zero, we can achieve this by ANDing the number with 254 (i.e. 11111110 in binary). 

101 101 IX 
AND 11111110 



10110110 



Unfortunately, the clarity of the process is obscured when the binary numbers are converted to 
their decimal equivalents. 

For instance, although it may seem unlikely at first sight, 

127 AND 129 = 1 

01111111 = 127 
AND 1000000 1 = 129 



00000001 = 1 

In spite of its superficial complexity, the technique of masking must be mastered if we are to use 
microprocessors or microcomputers in control applications. 

We have seen that we can clear any desired bits - i.e. reset them to - by ANDing a number with 
a suitable mask. We may also set a bit or bits to 1, using the logical operation OR; the remaining bits 
are unaffected. 

For example 127 OR 128 = 255 

01111111 = 127 
OR 10000 000 =128 



11111111 = 255 
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If we OR a number with a mask containing only a single 1, then the corresponding bit of the 
original number will be set to 1, regardless of its original value 

xxxxxxxx 

OR 00001000 



XXXX1XXX 



so that for example 



10101X01 
OR 00000100 



10101101 
Both these techniques are used in the programs which follow. 

Example 13.5 

This program shows how each bit in turn of a number read in from the user port may be checked. 

160 REM *************** 

110 REM * INPUT MASKING* 

120 REM *EAF 1982 * 

138 REM *************** 

140 

150 PRIHT"3:iON'T FORGET TO CLOSE THE DATA ISOLfiTION SWITCHES" 

160 PR I NT "THE NUMBER SET ON THE DATA SWITCHES IS READ IN AND PRINTED OH SCREEN" 

170 FOR J=l TO 2000:NEXT J 

ISO 

190 POKE59459..0:REM SET ALL DATA LINES TO INPUT 

200 N 1=256: REM ENSURES PRINT-OUT AT START 

210 N=PEEK<59471> :REM READ INPUT 

220 IF N1=N GOTO 210:REM REWRITE DISPLAV ONLV IF N CHANGES 

230 PRINT"3N ="N 

248 

256 REM NOW CHECK EACH BIT IN TURN BV MASKING THE INPUT DATA 

260 

270 FOR J=7 TO STEP -1 

2S0 NK<J>=8 

290 IF 2TJ AND H THEN NKCJ)=1 

300 PRINT"BIT"J" ="HK<J> 

310 NEXT J 

320 N1=N 

330 GOTO 210 

This program displays the value of each bit separately, changing the readout as the input signal 
varies. 

13.7 THE HANDSHAKE LINES - CA1 AND CB2 

So far we have not considered the significance of the control or "handshake" lines CA1 and CB2. 

In the simple examples considered so far, the data presented at the input has been stable - i.e. it 
has not been changing rapidly. In a real control system this is often not the case - for instance the 
output from an analogue-to-digital converter may vary almost continuously. In a case like this, it is 
necessary to ensure that data should be accepted only when the signals presented to the user port are 
valid. 

To achieve this, the "handshake data register" (HDR) is used. This lives at address 59457 
($E841). Data are latched into the HDR from the data register only when line CA1 detects a 
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transition from to 1 or from 1 to 0. We can choose to trigger the latching process on either a 
positive-going or a negative-going transition. 

When a pulse on CA1 causes data to be latched into the HDR, a 'flag' bit in yet another register 
(the 'interrupt flag register' or IFR) is set to 1. Until this occurs, the number in the HDR wi 1 change 
with that in the DR; once the flag bit is set, either by a latching pulse on CA1 or by a suitable POKE 
command, the contents of the HDR remain unaltered until they have been read (e.g. by PEEKing 
location 59457) or the flags reset to zero by a suitable POKE instruction. Reading the contents of the 
HDR clears the corresponding flag bit in the IFR and frees the HDR to follow the contents of the DR 
until the next latching or "handshake" pulse is received. 

The latching process is controlled also by bits in two more registers of the 6522, the "peripheral 
control register" or PCR (memory location 59468) and the "auxiliary control register" or ACR 
(memory location 59467). These registers, along with the IFR, are shown in Figure 13.8 below. 



Figure 13.8 
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N.B. In these registers, bits other than those marked control various internal operations within 
the PET. Great care should therefore be exercised when POKEing these locations. 



It will be seen that bit 1 of the IFR acts as the flag which indicates whether or not data have been 
latched into the HDR. The value of this bit can therefore be checked by PEEKing location 59469 (the 
IFR) and ANDing the contents with 2 (0000001 0) . If the result is non-zero then valid input data have 
been latched into the handshake data register (location 59457). We may alternatively use the WAIT 
instruction This suspends operation of the machine until a specified bit or bits of a memory location 
go high. In the case of the CA1 flag in the Interrupt Hag Register, the appropriate instruction is 

WAIT59469,2 
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However the WAIT instruction can be troublesome. Until the specified bit pattern is received, 
the machine will obey no further BASIC instructions and even the RUN/STOP key will not restart it. 
If, therefore, you make a mistake or the external circuit fails to deliver the appropriate signal, the only 
way to recover is to switch off the PET and start again, unless you have fitted a RESET switch to the 
machine. 

The latching or "handshaking" mechanism is enabled or disabled by setting bit of the Auxiliary 
Control Register (memory location 59467) to 1 or respectively. Positive-edge or negative-edge 
triggering is selected by bit of the Peripheral Control Register (PCR). If this is set to 0, the CA1 
input will be triggered by a negative-going edge (Figure 13.9). 



CA< Input 



PCR bit = 



CA4 triggered 

Figure 13.9 
If bit of the PCR is set to 1, CA1 will trigger on a positive edge . (Figure 13.10). 



CA1 Input 



PCR bit 0=< 



CA1 triggered 

Figure 13.10 

Example 13.6 shows how a signal on CA1 latches data into the handshake data register. The 
reader should confirm that latching does, in fact, occur only for the specified direction of transition on 
CA1 (but see notes on contact bounce). 



Example 13.6 



100 
110 

126 
138 
140 
150 
160 
170 
180 
190 

280 

210 
220 
230 
240 



SET LATCHING 

POSITIVE-EDGE TRIGGERING 
TRIGGERING <P OR N)";R* 



REM HANDSHAKE-CA1 
REM ************* 

PR I NT "IT 

POKE 59467 , PEEK < 59467 ) OR 1 : REM 

POKE 59468 , PEEK < 59463 ) OR 1 = REM 

INPUT "POSITIVE- OR NEGATIVE-EDGE 

IF LEFT$<R*, 1>="P" THEN GOTO 190 

POKE 59468, PEEK < 59468) AND 254: REM NEGATIVE-EDGE TRIGGERING 

PRINT'TTLOSE ALL DATA AND ISOLATING SWITCHES" 

PR I NT "WW SET DATA SWITCHES TO DESIRED NUMBER" 

PR I NT "THEN PRESS CA1 SWITCH AND SET DATA 

PRIW'MWWHEN VOU HAVE DONE, THAT PRESS ANV KEV 

GET A*: IF A$="" THEN GOTO 240 



SWITCHES TO A NEW NUMBER" 
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256 F=0:IF PEEK < 59469 ) AND 2 THEN F=l:REM CHECK FLAG 

260 L=PEEK < 59457 ):n=PEEK<: 59471): REM READ HDR AND DR 

270 PRINT"MKFLAG BIT ="F 

280 PR I NT "HDR CONTENTS ="L 

290 PRINT"DR CONTENTS ="U 

300 FOR 1=1 TO 2000: NEXT I 

310 PRINT"MWONCE READ, THE REGISTER IS UNLATCHED : ON RE-READING," 

320 F=@:IF PEEK < 59469) AND 2 THEN F=1=REM CHECK FLAG 

330 L=PEEKC59457):U=PEEK( 59471) -REM READ HDR AND DR 

340 PRINT"W1!FLAG BIT ="F 

350 PR I NT "HDR CONTENTS ="L 

360 PRINT"DR CONTENTS ="U 

370 END 

In general, it is unwise to alter the contents of the control registers, except for the specific bits 
detailed here. The VIA is an integral part of the PET, which may be brought to a state of complete 
immobility by incautious POKEing. Should this occur, the machine must be switched off to reset all 
the register contents to normal. 



13.8 CONTACT BOUNCE 

When a mechanical switch is closed, the contacts often bounce apart after initially making contact. 
Instead of applying a single voltage step to the attached circuit, the switch may thus apply several 
undesired pulses in rapid succession as the contacts bounce open and close again before the system 
settles down. There are a number of ways in which the effects of such contact bounce may be negated, 
but in microcomputer applications it is easiest to use "software debouncing". 

The switch contacts normally bounce for no more than a few milliseconds, and all that is 
necessary is to introduce a short delay after the first closure of the switch is detected, before allowing a 
further signal to be accepted from that switch. For instance, program 13.7 will time the interval 
between successive input pulses on CA1. 

Example 13.7 

120 REM Cfll INPUT TIMER 
130 REM *************** 

140 frint-zfress cm FOR INPUT" :N=0 

150 : 

160 P0KE59468, PEEK •: 59468::' OR 1 : REM SET Cfll TO DETECT +TIVE EDGE (SET PCR BITS TOO 

170 : 

180 fl=PEEK < 59457 > : REM RESET Cfll FLAG IN IFR BV READING HDR 

1 90 : 

200 IFPEEK'::59469>RND2THEH230:REM CHECK CHI FLAG IN IFR. IF E'IT1 = 1 THEN PROCEED 

210 : 

220 GOTO 208 

230 P=l+P :IFN=1 THEN 270 

240 PRINT"3FIRST INPUT DETECTED ON Cfll" 

250 T=TI :N=1 

260 GOTO 1 80 

270 PRINT"BSECOND INPUT DETECTED ON CHI" 

280 T 1 = . 8 1 * I NT C 1 00* < T I -T > /SS > 

290 PR I NT " Hr I ME BETWEEN I NPUTS= " : T 1 ; " SECS " 

300 PRINT"HNUMBER OF INPUTS=".:P 

310 IFTK.2THEH PRINT"MCONTflCT BOUNCE! TRV AGAIN 

320 PR I NT "MPRESS HNV KEV TO CONTINUE 

330 GETfl*:IFFiS=""THEN 330 

340 PR I NT "3 

350 GOTO 1 40 
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13.9 THE CB2 HANDSHAKE LINE 

This can be used as either an input or an output; in the latter case, a number of additional facilities 
render it very versatile. 

There are associated with the CB2 line a timer and a shift register (SR). The timer works by 
counting a specified number of cycles (up to 255) of the PET's 1-MHz master clock. When the 
appropriate number of clock cycles has passed, the timer sends a shift pulse to the shift register, and 
starts counting from zero once more. 

A shift register is a register in which the contents can be shifted along at will on receipt of a 
suitable shift pulse. In the case of the 6522 VIA, it is possible to arrange matters so that as the contents 
are shifted to the left, the bit shifted out of the highest-order position is fed to the CB2 line, and 
simultaneously fed back into the lowest-order bit position (see figure 13.11). The eight bits initially 
loaded into the SR can therefore be cycled round and round continually, moving along 1 bit position 
every time the timer indicates the passage of a specified number of clock cycles, so that a correspond- 
ing regular cyclic 8-bit pattern is sent out on the CB2 line. The rate at which this signal is sent, and 
hence the frequency of the output signal on CB2, is under the control of the programmer, who can 
load into the timer any number between 1 and 255. 
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Figure 13.11 



13.10 CB2 AS INPUT 

When CB2 is to be used as an input line the shift register must first be disabled by clearing bits 2, 3 and 
4 of the ACR (Auxiliary Control Register) to 0. This is done by the command 

POKE59467,PEEK(59467)AND227 

Bits 5 and 7 of the PCR must be set to 0, and bit 6 of the PCR must be set to or 1 , according to 
whether handshaking is to take place on negative or positive edges, respectively. 

When CB2 is triggered, bit 3 of the IFR is set. However, it will be found that it is reset almost 
instantly, as port B is constantly read by the PET in its normal operation. A handshake pulse on CB2 is 
therefore best detected by the WAIT instruction; it will be found that the alternative PEEKing and 
masking procedure, which works well on CA1, cannot be used. Furthermore, the data register need 
not be PEEKed or the IFR POKEd to reset the flag, although this would normally be necessary if the 
PET were not itself carrying out the process continually. 

In its input mode CB2 is most useful in timing applications. Successive pulses on CB2, or on CA1 
and CB2, may be detected and the time interval between these events can then be determined either 
by means of the PET's internal clock (TI or TI$) or by means of a simple machine-code routine. This 
principle is the same as that demonstrated in Example 13.7. 

13.11 CB2 AS OUTPUT: SOUND GENERATOR 

When used as an output, CB2 can supply a reasonable amount of current - 1mA at 1 .5 V. In addition 
to its use as a handshake output, indicating that valid output data are present on port A, it can 
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therefore also be used to drive quite basic electronic devices, such as a simple sound box. This is 
particularly useful when used in connection with the shift- register and timer facilities. 

As before, if CB2 is to function as a handshake line, the SR must be disabled by clearing bits 2, 3 
and 4 of the Auxiliary Control Register. Bits 6 and 7 of the PCR are set to 1 . The signal on CB2 is then 
controlled by bit 5 of the Peripheral Control Register. CB2 then goes high if this bit is set to 1, and low 
if it is reset to 0. The procedure is illustrated in the program below, which repeatedly switches CB2 
between its two states, with a short delay. 

Example 13.8 

100 REM ***************** 

110 REM *CB2GUTPUT BLINK* 

120 REM *EHF 1982 * 

130 REM ***************** 

140 

158 PR I NT "REMEMBER TO OPEN THE HANDSHAKE ISOLATING SWITCHES!" 

160 

170 PQKE59467, PEEK < 59467 >AND227: REM DISABLE SHIFT REGISTER FUNCTION 

180 P0KE59468.. PEEK •; 59468 > AND 31 OR 192:REM SET CB2 LOW 

190 FOR 1=1 TO 100: NEXT I 

280 P0KE59468. .PEEK.C 59468 > AND 31 OR 224 :REM SET CB2 HIGH 

210 FOR 1=1 TO 1S0:NEXT I 

220 GOTO 180 



13.12 SHIFT REGISTER OUTPUT 

As previously described, if the shift register is enabled, its output is fed directly to CB2, at a rate which 
can be determined by the count loaded into the timer. The shift register can be used in a number of 
ways, but most are useful only when used with machine-code programs. So far as the BASIC 
programmer is concerned, only the free-running mode described above is useful. 

The SR is enabled in its free-running mode by setting bits 4, 3 and 2 of the Auxiliary Control 
Register (ACR) to 1, 0, respectively. When this is done, the bit shifted out of bit location 7 of the SR 
is fed to CB2 at the same time as it is fed back into bit of the SR. The number in the SR is shifted one 
bit every time the timer completes its count. CB2 can thus be fed with a repetitive train of rectangular 
pulses. If the output from CB2 is then fed to a simple amplifier, musical and other sound effects can be 
obtained. If an audio amplifier is already available, this may be used. If not, the following circuit, 
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which can be powered from the cassette port, is adequate. Almost any small-signal n-p-n transistor can 
be pressed into service; a p-n-p device may also be used if the circuit is suitably re-arranged. 

Any desired number can be loaded into the shift register (memory location 59464), and the 
counter can similarly be loaded with any desired number from 1 to 255, by POKEing memory location 
59464. 

It should be noted that once this is done, the 6522 will continue to deliver a continuous output to 
the CB2 line indefinitely, without any further attention from the microprocessor. The PET can 
therefore carry out other operations at the same time as generating this audio ouput. This may be seen 
in the familiar 'Space Invaders' game. 

The highest possible frequency (which is quite inaudible) is obtained by loading the counter with 
1, and the shift register with alternating O's and l's. This may be done by POKEing memory location 
59466 (the SR) with 85 (01010101) or 170 (10101010). This produces a signal which changes from 
high to low or vice versa with every clock pulse - i.e. at a rate of 500kHz. 

The lowest possible frequency is obtained by loading the counter with 255 and the shift register 
with 15 (00001 1 1 1) or 240 (1 1 1 10000). This is clearly slower by a factor of 255 x 4, or 1020, so that 
the frequency will be 490.2 Hz. 

Between these two values a whole range of frequencies is available, so that it is quite possible to 
use the PET as a rather crude electronic organ. It should be noted that the frequency of the signal is 
extremely precise and stable, since it is derived directly from the PET's crystal oscillator. The PET can 
therefore be used for technical purposes as a pulse or square-wave generator giving great precision of 
timing. 

Some of the possibilities are demonstrated in the programs which follow. 

Example 13.9 

This allows the user to load any desired numbers (up to 255) into the counter and shift register. The 
corresponding signal is fed to CB2, and the waveform of the signal is displayed on the screen. This 
program is particularly instructive, since the effect of changing the contents of the shift register, and 
hence the output signal waveform, is instantly obvious both to the eye and the ear. 

160 REM **************** 

1 1 REM *CB2 SOUND DEMO* 

120 REM *EAF 1982 * 

130 REM **************** 

140 

156 PRIHT"3THIS PROGRAM GENERATES flN ALTERNATING OUTPUT SIGNAL OH CBS. "; 

160 PRINT" IT USES THE BUILT-IN SHIFT REGISTER AND COUNTER OF THE 6522,"; 

178 PRINT" ALONG WITH THE CRVSTAL-CONTROLLED SYSTEM CLOCK 

180 

190 REM ENABLE SHIFT REGISTER 

200 P0KE59467, PEEK < 5946? > AND 227 OR 16:REM SET ACR BITS 2tf<3 TO 0,BIT 4 TO 1 

210 

220 PRIHT"SJINPUT A NUMBER < 0-255 > TO SET COUNTER" 

230 INPUT C 

240 P0KE59464,C:REM SET COUNT IN TIMER 2 OF 6522 

250 INPUT" HI NPUT A NUMBER TO BE LOADED INTO THE SHIFT REGISTER" ;H 

260 N*="" :NN*="" 

276 FOR J=7 TO STEP -1 

280 NN*< J>=STR*<0> :H*CJ:> = "" 

290 IF H AND 2tJ THEN NN*< J>=STR*< 1 ':> :GOSUB 470 

300 IF NOT N AND 2t.J THEN GOSUB 430 

3 1 HH*=NN*+NN* < J > : N*=H*+N* C .J > 

320 NEXT J 

330 PRINVaSINARV EQUIVALENT IS "NN*"H" 

340 PR I NT "WAVEFORM IS ";:IF VRL < NN* ■'. 7 > > = 1 THEN PRINT " I"; 

350 PR I NTN* .: : I F VAL C HN* •; > > = 1 THEN PR I NT " I " ; 
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366 POKE 59466 ,N: REM LOAD SHIFT REGISTER 

370 PRINT: PR I NT 

380 PRINT "PRESS SPACE BAR TO STOP; ANV OTHER KEV TO INPUT A HEW NOTE" 

390 GET A*: IF A*=" " THEN GOTO 390 

409 IF A*=" " THEN GOTO 420 

410 PR I NT" 3" : GOTO 280 
428 END 

436 IF J=7 THEN N*< J>="_" :GOTO 460 

440 IF HN*';j+l>=NN*CJ> THEN N*< J :> = "_": GOTO 460 

450 n*cj:j = "L" 

466 RETURN 

470 IF J=7 THEN N*< J > = """" :GOTO 560 

4S0 IF NN*';j+l>=NN*':j> THEN N*<J> = ""~" :G0T0 500 

496 N*< J > = "[-" 

500 RETURN 



Example 13.10 

In this program the shift register is loaded with a fixed number, 1 5 , to give a square-wave output, while 
the timer is loaded with the ASCII value of a character from the keyboard. Every time a different key 
is pressed, a new note is produced, so that with some care simple tunes can be played on the PET 
keyboard. 

100 REM PET KEVBOARD MUSIC 

110 REM ##***#*****#*****# 

120 

130 PRIHT"3=ET KEVBOARD MUSIC PROGRAM" 

140 PR I NT "PRESS KEVS IN TURN TO PRODUCE NOTES" 

150 PR I NT "PRESS RETURN TO STOP" 

160 

178 GET A*: IF A*="" THEN GOTO 170 

180 IF A*=CHR*>:i3> THEN GOTO 230 

190 POKE 59467, PEEK < 59467 > AND 227 OR 16:REM SET SR TO FREE-RUNNING MUDE 

200 POKE 59466, 15 :REM LOAD SR WITH SQUARE WAVE 

210 POKE 59464,ASC<A*> :REM SET TIMER 

220 GOTO 178 

230 POKE 59467, PEEK < 59467 > AND 239 :REM DISABLE SR 

240 END 



Example 13.11 

The principle is extended in the next program by loading the counter with numbers read in by means 
of DATA statements. If these are carefully chosen, quite presentable music can be produced. 

180 REM PET MUSIC. FROM DATA 

110 REM **#*####**********# 

120 

138 PRIHT":FET MUSIC PROGRAM" 

140 PR I NT "PRESS ANV KEV TO STOP" 

150 

168 POKE 59467, PEEK< 59467 > AND 227 OR 16:REM SET SR TO FREE-RUNNING MODE 

178 POKE 59466, 15 :REM LOAD SR WITH SQUARE WAVE 

188 READ A: IF A=l THEN RESTORE : GOTO 188 

190 POKE 59464, A: FOR J=0 TO 100: NEXT J 

200 GET A*: IF A*="" THEN GOTO 188 

218 POKE 59467, PEEK < 59467 > AND 239 :REM DISABLE SR 

228 END 

238 DATA 79, 78, 58, 58, 8, 58, 0,0, 78, 7y, 78, 79, 95, 79 

240 DATA 8 .0.79, 78, 58, 58, 8,58, 8,0, 78 

258 DATA 79.78,79,95,79,0,8,186,97,106,119,119,119, 

268 DATA 8.8.185,96,185,118,118,96,185,118,118,100,96,8,8,0,1 
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The programs presented here form only an introduction, and the user will doubtless be able to 
devise many variations on the basic theme. 

WARNING When the shift register is enabled in the cyclic mode, it will be found that programs 
cannot be SAVEd. If the SR is enabled in this way during the course of a program, then it should be 
disabled again before exiting from the program, by clearing bit 4 of the ACR. 

If the program is interrupted by means of the RUN/STOP key, then the SR should be disabled by 
the immediate mode command 

POKE59467,PEEK(59467)AND239 

or more simply 

POKE59467,0 

before attempting to SAVE the program (or indeed any other). Alternatively, of course, the ACR 
may be reset by the usual rather drastic process of turning the machine off and on again. 



IF THE SHIFT REGISTER IS NOT DISABLED IN THIS WAY BEFORE ATTEMPTING 
TO SAVE A PROGRAM ON DISK, ANY OTHER PROGRAMS ALREADY ON THE DISK MAY 
BE RENDERED UNREADABLE. 



CHAPTER 14 

Loading and Running 
Machine-Code Programs 
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Loading and Running 
Machine-Code Programs 



INTRODUCTION 

It is sometimes found that the PET is just not able to operate quickly enough to perform a particular 
task. This may occur, for example, when trying to change the screen display rapidly in a graphics 
program or when trying to use the user port to time fast-moving objects. In the majority of cases this 
problem is caused by the time it takes the PET to recognise and obey BASIC instructions. Thus, each 
time a BASIC instruction is encountered, the BASIC 'book of rules' inside the PET must be consulted 
so that the instruction can be recognised and the correct action taken. The BASIC instruction, when 
interpreted, becomes a set of coded binary numbers which the 6502 microprocessor at the heart of the 
PET can understand. It would clearly be much quicker if the program instructions could be written 
directly in this binary coded form instead of in the high-level language BASIC. This is the basis of 
machine-code programming. The resulting increase in speed is spectacular. In some cases the PET will 
execute a machine-code program several hundred times faster than the equivalent program written in 
BASIC. 

It is not intended here to become involved with the intricacies and techniques of machine-code 
programming because the subject is vast. The reader is referred to one of the many books on 6502 
assembly language programming which are available. However, it is helpful to examine how a 
machine code program may be loaded into a PET and then run. There are various ways in which this 
may be achieved. 

14.1 DIRECT POKEING FROM BASIC 

The BASIC commands POKE and PEEK are very powerful in that they can access any of the 
Random Access Memory (RAM) locations used by the PET, whereas the other instructions operate 
only in that section of memory reserved for BASIC programs. Thus, the POKE command can be used 
to POKE a machine-code instruction into any suitable location. It is obvious that this technique 
should be used with great care. Large sections of the memory are used to control the internal workings 
of the PET and, should a rogue instruction be POKEd into such a location, it is likely that the machine 
would be totally disabled. In such cases, the only solution is to switch off and then on again for a fresh 
start losing, of course, any existing program in the machine in the process. However, there are some 
regions of the memory which are relatively safe and secure. The most commonly used of these is the 
space reserved for the operation of the second cassette. Since this is only rarely used these locations 
are commonly regarded as 'fair game'. The second cassette buffer is placed between locations 826 and 
1017 in decimal i.e. between $033A and $03F9 in hexadecimal. 

The use of hexadecimal notation is an important technique in machine-code programming. As 
the name implies, hexadecimal is a number system with a base of 16, the decimal numbers 10, 1 1, 12, 
13, 14, 15 being represented by the alphabetic characters A, B, C, D, E, F respectively. The use of 
hexadecimal greatly simplifies the tedious problem of writing machine-code instructions in binary 
notation. For example, suppose we wish to write the binary instruction 11101010. Such a group of 
eight binary digits is called a BYTE. In hexadecimal this byte would be written simply as EA (i.e. E x 
16 + Axl = 14xl6 + 10xl = 234). The hexadecimal version is clearly much less laborious to use 
and is less prone to error. The PET simply takes the hexadecimal characters and converts them into 
the binary equivalent for its own use. (Thus E = 1110 and A = 1010 so EA = 11101010.) 
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Conversely, on output, the PET converts from binary to hexadecimal for the convenience, and sanity, 
of the user. In order to be able to identify hexadecimal numbers when printed or written they are 
usually preceded by the $ sign. 

The POKE address and argument must always be in decimal. This can be a nuisance if the user is 
more familiar with hexadecimal notation because the corresponding decimal numbers will be unfamil- 
iar. (This can be overcome by the use of more sophisticated loader programs, as discussed later.) 

Having placed the program in some safe region of the memory, the PET must now be directed to 
the start location in order to run the program. It is not possible to use the RUN command because this 
only operates on a BASIC program. The most convenient command to use is SYS. Thus, if the start 
location of the machine code program is in decimal location 826, then the BASIC command SYS 826 
will start the program. The program will continue to run until a special instruction in the program 
returns the PET to BASIC operation. This command is the 'Return from Subroutine' command (code 
96 in decimal or $60 in hexadecimal). If the original SYS command was a direct (i.e. keyboard) 
command then, on return to BASIC, the normal READY response will be displayed. If the SYS was 
part of a BASIC program then, on returning to BASIC, the next instruction of the BASIC program 
will be obeyed. 

Consider the following simple program :- 
Example 14.1 

18 POKE 326,234 
29 POKE 827,96 
•"30 SVS 82'fi 
40 END 

In line 10 the first location in the second cassette buffer is loaded with 234, i.e. $EA. Line 20 
loads the next location with 96, or $60. Line 30 is the SYS command pointing the PET to the first of 
the machine-code instructions. On RUNning the program the machine-code instructions are loaded 
and the SYS command causes the instruction in 826 to be obeyed. This instruction is, in fact, a No 
Operation instruction which has no effect at all (just as a BASIC REM has no effect on the running of 
the program) . The next instruction, in 827, is a Return from Subroutine command and returns control 
to BASIC where the next instruction is END. Thus the sum total effect of this program is to do 
nothing! However, it does show how machine-code programs can be handled. Note that the machine- 
code needs to be loaded only once. The locations holding the program are not affected by the BASIC 
command NEW nor, if chosen correctly, by the loading of another BASIC program from disk or 
cassette. Thus, after being loaded, the machine-code instructions may be called repeatedly within the 
same BASIC program or even from other BASIC programs. Only re-POKEing the locations or 
switching off the PET will disturb them. 

If the second cassette buffer is required during a program it is then, of course, not possible to use 
these locations to house any machine-code instructions. A useful technique in such cases is to create a 
reserved region at the top of PET's memory. This is done by fooling the PET's operating system into 
thinking that the available memory is smaller than it really is. The address of the highest available 
memory location is stored in the PET in locations 52 ($ 34) and 5 3 ($ 35) . The higher order byte of this 
address is stored in location 5 3 and the lower order byte in location 5 2. Therefore , if we change either 
of these numbers, the apparent size of the available memory will be altered. By this means we can 
create our own protected area at the top of memory which will not be used by the PET's BASIC 
interpreter. 

For instance, a protected area of 256 bytes will be created if the higher order byte of this upper 
RAM pointer is reduced by 1. It is not necessary to know the old value of this pointer. It may be 
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reduced by the required amount simply by using a combination of PEEK and POKE commands: 

POKE 53,PEEK<53>-1 

The lowest reserved address is then readily calculable in decimal form: it will be: 

PEEK < 53 ) #256+PEEK < 52 > + 1 

It can be seen that any desired amount of RAM space (within the limits set by the PET's memory 
size) may be reserved by this method provided that a reasonable amount of RAM is left for use by the 
BASIC interpreter. 

14.2 THE USE OF LOADER PROGRAMS 

A loader program is simply a development of the method of using POKE to place machine-code 
instructions in the memory . This type of program may either be called a machine-code loader, because 
it loads machine-code, or it may confusingly be called a BASIC loader because it loads from a BASIC 
program. Instead of POKEing each instruction individually the loader program handles all the 
machine-code instructions as a block of DATA statements. Each machine-code instruction is READ 
and POKEd sequentially into the memory, starting at a specified location. 

Example 14.2 

18 GOSUB 1888 



38 END 

1888 REflB S:REM S=START LOCATION 

1818 READ fl:IF A<8 THEN RETURN 

1828 IF A>255 THEN 1848 

1838 POKE S,A : S=S+1 : GOTO 1818 

1848 PRINT "BVTE"S"=["R"3 ???" : END 

1858 DATA S32 

1868 DATA 128.. 169. 79, 133.. 144, 1 69.. 3.- 133.. 145.. 169.- 1 

1 878 DATA 1 33 , 2 , 88 , 96 ,165,151,197, 8 ,24 8 , 9 

1888 DATA 133,8, 169, 16, 133, 1 , 76,(g53(228> 281 ,255 

1898 DATA 248, 249, 165 ■ 1 , 248, 4, 198, 1 , 288, 241 

1188 DATA 198,2,283,237,169,4,133,2,169,8,133,151 

1118 DATA 169,2, 133, 163,288,223,--! 

This program may be used to provide a 'repeat' facility when any of the PET's keys is held down. 
It is a good example of the type of machine-code program which can be loaded and forgotten while the 
user continues to operate the machine in BASIC, load in other BASIC programs etc, while still 
employing the machine-code program. The operation of the loader part of the program is as follows. 
Line 10 calls the loader sub- routine which starts at line 1000. Here the value of S is READ from the 
data and this gives the starting location for the machine code program. In 1010 the first instruction 
byte is READ into variable A. If this byte is found (line 1020) to be valid it is POKEd (line 1030) into 
the location specified by S; if it is invalid the program ends with an error message (1040) . The value of 
S is then incremented by 1 and the process is repeated for the next byte. If the exact number of data 
bytes in the program is known, the loading operation can be controlled by a FOR . . . NEXT loop. A 
more flexible technique is to make the process open-ended and terminate the operation with a 
terminating character at the end of the data. This is achieved here by the introduction of a negative 
number in the last data position, causing a RETURN to be executed from line 1010. The machine 
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code instructions are now in place and it only remains to call the program with a SYS (in line 20) to the 
starting location. (N.B. This program was written for a 4000-series machine. To make it run on a 2000 
or 3000 series machine it is necessary to replace the two circled bytes with the decimal numbers 46 and 
230 respectively.) 

The main disadvantage of the above program is that the instructions and locations must be in 
decimal. This can be a serious disadvantage because one becomes familiar with the hexadecimal 
version of a program as it is being developed and modified, but once all the bytes have been converted 
into decimal it becomes unrecognisable. A solution is to use a version of the loader which automati- 
cally converts from hexadecimal to decimal before the bytes are POKEd. 

Example 14.3 

18 nnsuB 1900 

28 SVS 832 

30 END 

1000 READ S 

1010 READ fl*:|_=LEN<fl*>:IF fl*="*"THEN RETURN 

1828 IFLX1 OR L>2 THEN 1090 

1830 N=0:IF A*>"" AND LEN<fl*X3 THEN 1959 

1040 GOTO 1098 

1858 FOR J=l TO LEN<R*>:X=flSC<MID*<fl*, J,-l)>-48 

1060 N=N*16+X+<X>9>#7:NEXT J 

1878 IF N<0 OR N>255 THEN 1998 

1 838 POKE S , N : S=S+ 1 •■ GOTO 1818 

1 890 PR I NT " BVTE " S " = C " A* " 1 ??? " : END 

1100 DATA 832 

1118 DATA 78 , A9 , 4F , 85 , 9© , A9 , 03 , 85 , 9 1 , R9 , 8 1 

1 1 20 DATA 85 , 02 .. 58 , 68 , A5 , 97 , C5 .- 08 , F8 , 89 

1 1 38 DATA 85 , 88 , A9 , 1 8 , 85 , 8 1 , 40 ,@.Q). C9 , FF 

1 1 40 DATA F0 , F9 , A5 , 8 1 , F0 , 84 , C6 .. 8 1 , D8 , F 1 

1 1 50 DATA Cfi , 82 , D8 , ED , A9 , 84 , 85 , 82 , fl9 , 80 , 8b , 97 

1168 DATA A9,82,85,A8,D0,DF,* 

It can be seen that the data statements in lines 1 1 1 to 1 1 60 are now written as hexadecimal bytes 
and the program is quite recognisable to anyone who is familiar with it in hexadecimal form so that, as 
a result, the program may be modified easily by modifying the data. The operation of the loader is very 
similar to that of the previous example. The data are now treated as strings and the terminator is a 
string character, a " * " . The main interest lies in lines 1 050 and 1 060 where the hexadecimal bytes are 
converted into their decimal equivalents. In 1050aFOR. . .NEXT loop is set up of length equal to the 
number of characters in the hexadecimal byte. (This is always equal to 2 if the data is written as in this 
example but, in fact, the leading zero in, for example, 01 or 04, could be omitted.) The ASCII value 
of the first character of the byte is then determined, 48 is subtracted from it and this number is 
assigned to the variable X. This is because the ASCII values for the numerals to 9 start at the value 
48 so that subtracting 48 from the code gives the numerical value. In 1060, on the first cycle of the 
FOR . . NEXT loop, N is set to this value. However, a problem occurs if the character is one of the 
special hexadecimal characters A to F. The ASCII value for A does not follow on immediately from 
the ASCII value for 9 but instead there is a gap of 7 between them. Thus ASCII 9 = 57 but ASCII A = 
65. This means that in these cases the value of X will be too large by 7. The solution is to employ a 
logical operator. Thus, in line 1060, X is added to N and the term (X>9) *7 is also added. The term in 
brackets has the property of being zero if X is not greater than 9 and being -1 if X exceeds 9. Thus, in 
the case where the character is a numeral between and 9 this term is zero, but when one of the letters 
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A to F is encountered a further 7 is subtracted from the ASCII value. At the end of line 1060 the FOR 
... NEXT loop is re-entered to convert the second character of the byte (if present) . When line 1 060 is 
reached again, the old value of N is again multiplied by 16 after which it is added to the computed 
value of the second character. After the final value of N has passed its validity test in line 1070, it is 
POKEd into its location and the next byte is READ in. 

This loader is a useful device for loading machine code from BASIC and the technique is very 
widely used. Its main disadvantage is that it is rather slow compared with the decimal loader and this 
can be annoying when long machine-code programs have to be loaded, because the PET is effectively 
disabled during this period. (N.B. This program was written for a 4000 series machine. To make it run 
on a 2000 or 3000 series machine it is necessary to replace the two circled bytes with the values 2E and 
E6 respectively.) 

14.3 THE TERMINAL INTERFACE MONITOR (TIM) 

The method of POKEing instructions into the PET's memory is effective, especially when performed 
by a loader program, but it has the disadvantage that it is difficult to make any changes without 
re-loading the entire program. The only way that a location can be checked from BASIC is to use the 
PEEK command, and only one location at a time can be examined with a single PEEK. 

The firmware of the PET includes an extensive program which, among other things, allows the 
contents of any memory location to be inspected and, if required, to be modified. The program is 
called the Terminal Interface Monitor known, somewhat sinisterly, as The Monitor or more familiarly 
as TIM. 

You will probably have met the monitor already. It has a habit of appearing, uncalled-for, in the 
middle of BASIC runs as a result of some error on your part. In this context the appearance of the 
monitor display usually heralds disaster. However, when under control, the monitor can be very 
useful. 

To call up the monitor intentionally, type SYS 4 and press RETURN. The monitor display will 
appear and will look something like:- 

B* 

PC IRQ SR AC XR VR SP 
. ; 0085 034F 30 00 5E 04 F6 



DON'T PANIC! This display is quite normal. The monitor is simply showing you the contents of 
the registers in the 6502 microprocessor at the heart of the PET. Thus, PC is the Program Counter, SR 
the Status Register, AC the accumulator, etc. Note that, when the monitor is in action, all numbers 
must be in hexadecimal form. 

Once you have invoked the monitor, the prompt signal is the full stop. This can be seen at the 
bottom-left of the above display. It is usually followed by the cursor, inviting an input from the 
keyboard. A number of single-letter commands are available to you when in the monitor:- 

M display content of locations specified 

R display registers 

G execute machine code program from specified address 

X exit to BASIC 

L load program (from cassette or disk) 

S save program (on to cassette or disk) 
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Probably the most useful command is M, the 'display memory' command. Thus, if you type:- 

M space start address, end address 
followed by RETURN 

e.g. .M 033A,034F 

the monitor will respond with a display which will look something like:- 

„M 033R/834F 

033A 01 00 00 00 01 00 00 FF 
0342 2fl 00 00 00 00 00 00 00 
034H 00 00 00 00 00 00 00 00 

m 

The characters on the left of the display, e.g. 033A, 0342, 034A are the locations being 
examined. The starting location and every 8th location thereafter are labelled but, in fact, the contents 
of every location in the specified range are displayed. Thus, on the first line, the contents of 033A to 
0341 are, respectively, 01, 00, 00, 00, 01, 00, 00, FF. In fact, the contents of the specified locations 
don't look very exciting. This is because no specific program has been placed in this part of memory 
since switch-on. If we look again at the same locations after a program has been loaded they may look 
quite different:- 

„M 033fl,034F 

033fl D0 F4 EE fil 03 D0 EF EE 
0342 fl2 03 4C 30 03 EC 41 E8 
034fl F0 10 EE B0 03 D6 DF EE 

Once the contents of a memory location or a register are on display they can be changed very 
easily. The cursor is moved, using the usual cursor control keys, until it is over the offending data and 
the new data are overtyped. When the modifications to a given line are complete the RETURN key is 
pressed, which writes in the new data. 

It is not necessary to return to BASIC to execute a program; it can be run directly from the 
monitor by typing:- 

G space start address 

followed by RETURN 

e.g. .G 033A 

Programs which are to be executed like this must terminate with a BREAK instruction ($00) 
rather than a Return from Subroutine ($60), to leave the user in the monitor at the end of the 
program. 

A program may be SAVEd directly from monitor using the command:- 

.S space "progname", 08, start address, end address PLUS 1 

followed by RETURN 

e.g. .S "TEST", 08, 033A, 0350 

will save on disk the program located between $033A and $034F. This will be saved on disk as normal 
under the program name TEST but it will be a machine code program. To SAVE on cassette the 08 in 
the above example must be replaced with 01. 
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The machine code program so SAVEd may be LOADed from monitor with the single instruc- 
tion :- 

.L "TEST",08 

(Again, 01 should be substituted for 08 for cassette operation. Alternatively, when LOADING, 
omission of the device number gives cassette operation by default.) 

It is also possible to LOAD the machine-code program without using the monitor by making use 
of the normal disk or cassette LOAD commands. The program will automatically be located in the 
correct position in memory. 

14.4 THE USE OF AN ASSEMBLER 

An assembler is a program which can be resident in firmware or on disk and allows the use of a type of 
programming language, which is of a slightly higher level than machine-code, called a mnemonic 
assembly language. Using such a language means that every possible machine-code instruction can be 
represented by a unique three-letter mnemonic. For example, $EA, the No Operation instruction 
referred to earlier, is represented by the mnemonic NOP; $60, a Return from Subroutine, is 
represented by RTS; $00, Break is represented by BRK etc. The complete program may be written in 
this form and then fed to the assembler which converts the mnemonics into the corresponding 
machine-code instructions. The advantage of this is that it is much easier to construct programs using 
the helpfully-spelt mnemonics than it is using the completely arbitrary machine codes, whether in 
hexadecimal, binary, or decimal. A further important advantage is that the assembler allows you to 
use labels within the program so that the wearisome task of calculating the addresses for jumps and 
branches in the program is undertaken by the assembler, not by you. 

Finally, having assembled the complete program in machine-code, the assembler loads the 
program into the memory locations specified so that all you have to do is RUN it, either from BASIC 
or from the monitor. 

This is, without doubt, the easiest and most effective way to develop and load machine-code 
programs and if lengthy programs are to be written an assembler is an essential programming tool. 

14.5 ELEMENTARY MACHINE-CODE EXERCISES 

The following elementary machine-code exercises are not presented as tuition in machine-code 
programming but simply as vehicles to demonstrate the LOADing and RUNning techniques discus- 
sed in this chapter. In the exercises a few of the commands of the 6502 instruction set are employed to 
perform some simple arithmetic operations. The programs may be POKEd manually from the 
keyboard, they may be POKEd from a BASIC program, they may be written and run from the 
monitor, or assembled and loaded with an assembler. Note that, if the monitor command .G is used to 
run the programs, the RTS instruction at the end of each program must be replaced by a BRK 
instruction, $00. 

WARNING When a machine-code program is run, any error in the program is likely to lock-up 
the PET completely. Control can usually be recovered only by switching the machine off and on again. 
This of course destroys any program in memory so, before running any machine-code program, it is 
wise to SAVE the program or at least to write it down! 

The following programs may be inserted at any convenient point within the memory space of the 
PET. Probably the simplest method is to make use of the second cassette buffer, which occupies 192 
memory locations extending from $033A-$03F9 (826 to 1017 decimal). For simplicity the addresses 
used below start from $033A, but the start address may of course be changed at will. 
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Exercise 14.1 

This program reads a number (here $AB) directly into the accumulator and then writes it into 
memory, at the arbitrarily-selected location $03F9 (1017 decimal). 

Address Machine- Code Instruction Mnemonic 

$033A A9AB LDA #$AB 

$033C 8DF9 03 STA [$03F9] 

$033F 60 RTS 

The program may be stored at the locations shown and then run using the appropriate SYS 
command. Remember that all the numbers are in hexadecimal. If the monitor is used to load the 
program, no difficulty arises, but if the program is to be loaded using POKE commands, both the 
addresses and the instructions must be converted to decimal form. Note that addresses in machine- 
code are written low-order byte first. Thus 03 F9 becomes F9 03. 

Exercise 14.2 

In this exercise the number is read into the accumulator from a specified memory location (here 
$03F0) and written into location $03EA. 

$033A ADF0 03 LDA [$03F0] 

$033D 8DEA03 STA [$03EA] 

$0340 60 RTS 

Check the operation of the program by POKEing different numbers (up to 255) into location 
$03F0 (1008 decimal) and PEEKing location $03EA (1002 decimal), after the program has been run, 
to confirm that they have been correctly transferred. 

Exercise 14.3 

Here a number is read from memory location $03F6 (1014 decimal) and loaded into the accumulator. 
A second number, read from memory location $03F7 (1015), is added to it and the result is stored in 
memory location $03F8 (1016). The carry flag must first be cleared, since if it is set to 1 the 
microprocessor will assume that there has been a carry from a previous addition and add this into the 
sum. The operation is: 

A + M +C -»A,C 

$033A ADF6 03 LDA [$03F6] 

$033D 18 CLC 

$033E 6D F7 03 ADC [$03F7] 

$0341 8D F8 03 STA [$03F8] 

$0344 60 RTS 

Note that none of the numbers, including the sum, must exceed a value of $FF (255). 

Exercise 14.4 

We may similarly subtract two numbers. In this case the carry must first be set to 1 since the SBC 
(subtract with borrow) operation is: 

A - M - C ->A, C 

Note that, if the subtrahend is greater than the minuend, the (negative) answer will be expressed 
in complement form and will be difficult to interpret. 
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LDA [$03E0] 

SEC 

SBC [$03E1] 

STA [$03E2] 

RTS 

Here, the contents of memory location $03E1 (993) are subtracted from those of location $03E0 
(992) and the result is stored at $03E2 (994). 

Exercise 14.5 

In this program the mean value of two numbers is calculated and rounded down. 



$033A 


AD E0 03 


$033D 


38 


$033E 


ED El 03 


$0341 


8D E2 03 


$0344 


60 



$033A 


18 


CLC 


$033B 


AD E6 03 


LDA [$03E6] 


$033E 


6D E7 03 


ADC [$03E7] 


$0341 


6A 


ROR 


$0342 


8D E8 03 


STA [$03E8] 


$0345 


60 


RTS 



The numbers to be averaged are read from locations $03E6 (998) and $03E7 (999) and their 
mean is stored at $03E8 (1000). 

The SED and CLD Instructions 

The PET's microprocessor, the 6502, may be set to add or subtract decimal rather than hexadecimal 
numbers, by means of the instruction SED (F8). The processor is returned to the hexadecimal mode 
by the instruction CLD (D8). 

N.B. It is in general good practice to set the processor specifically to the desired mode within 
every program you write, since it is always possible that some previous program has left it set to the 
wrong mode. 

Exercise 14.6 

Modify the programs of exercises 14.3 and 14.4 for the addition of decimal, rather than hexadecimal, 
numbers. Verify that the modified programs work as predicted. 

The NOP Instruction 

Where a machine-code program is subject to modification as in Exercise 14.6, the NOP or 'no 
operation' instruction (EA) will often be found useful. It may be used to fill unused memory locations 
within a program since the processor does nothing on receipt of a NOP instruction, simply advancing 
to the next instruction in sequence. 

Exercise 14.7: Branches and loops 

This program converts a two-digit decimal number, stored in location $03E0 (992), to a hexadeci- 
mal number stored in location $03F0 (1008). 

The decimal number is first copied into location $03E2 (994) and then progressively 
decremented. Simultaneously the number stored in location $03F0 (initially 0) is correspondingly 
incremented. At each step the value of the number remaining in $03E2 is checked. So long as this 
value is greater than zero, the program loops back and repeats the process. Once its value has been 
reduced to zero, the program exits from the loop by means of a branch instruction. 
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Location 


Instruction 


$033A 


AD E0 03 


$033D 


8D E2 03 


$0340 


A9 00 


$0342 


8D F0 03 


$0345 LOOP D8 


$0346 


EE F0 03 


$0349 


F8 


$034A 


AD E2 03 


S034D 


38 


$034E 


E9 01 


$0350 


8D E2 03 



$0353 



$0355 
$0356 



D0F0 



D8 
60 



Mnemonic 


Comment 


LDA 


[$03E0] 




STA 


[$03E2] 


Copy decimal number 


LDA 


#00 


Clear accumulator 


STA 


[$03F0] 


Clear hex count 


CLD 




Clear decimal mode 


INC 


[$03F0] 


Increment hex count 


SED 




Set decimal mode 


LDA 


[$03E2] 


Get decimal number 


SEC 




Set carry flag 


SBC 


#01 


Subtract 1 


STA 


[$03E2] 


Save decremented 
decimal number 


BNE LOOP 


Return to start of 






loop if decimal 






number ± 


CLD 




Clear decimal mode 


RTS 
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BASIC COMMANDS AND STATEMENTS 



COMMAND/ 
STATEMENT 



EXAMPLE 



PURPOSE 



ASC 


10 A = ASC("XYZ") 


CHR$ 


10 A$ = CHR$ (N) 


CLR 
CMD 


CLR 
CMD 5 


CONT 


CONT 


CLOSE 
DATA 


10 CLOSE L 
10 DATA 1,2,3,4 
20 DATA TOM,SUE 




30 DATA TOM," ", CAT 


DIM 


10 DIM A(n) 




20 DIM A(n,m,o.p) 


END 
FRE 
FOR . . . NEXT 


30 DIM A(n), B(m) 

40 DIM A(N) 

50 DIM A$(n) 

999 END 

PRINT FRE(0) 

10 FOR A = 1 TO 20 


GET 


90 NEXT A 
10 GET C 
20 GET C$ 
30 GET#L,C 
40 GET#L, C$ 


GOSUB 


10 GOSUB n 


GOTO 


GOTO n 




10 GOTO n 


INPUT 


10 INPUT A 
20 INPUT A$ 



IF 



THEN 



IF . . . GOTO 



LEFTS 

LEN 

LET 



30 INPUT A,A$,B.B$ 

40 INPUT#L,A 

50 INPUT#L,A$ 

60 INPUT#L,A,A$,B,B$ 

10 IF A=10 THEN PRINT A 



10 IF A=l GOTOn 



10 ?LEFT$(X$,A) 
10 ?LEN(X$) 
LET A = 2 



Returns integer value corresponding to ASCII code 

of first character in string. 

Returns character corresponding to ASCII code 

number. 

Sets variables to zero or null. 

Keeps open IEEE device specified in logical file, to 

monitor bus. 

Continues program execution after a STOP 

command.No program changes allowed. 

Closes logical file L. 

Specifies data to be read from left to right. 

Purely alphabetic strings do not need to be enclosed 

in quotes. 

If string contains spaces, commas, colons, or graphic 

characters, the string must be enclosed in quotes. 

Specifies maximum number of elements in an array 

or matrix. 

Specifies maximum number of elements in each 

dimension of a multi-dimensional array. 

Format for dimensioning two arrays. 

Format for dynamic dimensioning. 

Format for string arrays. 

Terminates program execution. 

Returns number of bytes of available memory. 

Loop control. Performs all functions between FOR 

and NEXT as many times as specified by index. 

In this example, the index variable is A. 

Accepts single numeric character from keyboard. 

Accepts single string character from keyboard. 

Accepts single character from specified logical file. 

Accepts specified single string character from logical 

file. 

Begins execution of a subroutine which begins on a 

specified line. 

Continue program execution at line n after a STOP 

command. Program changes are permitted. 

Transfers control (jumps) to specified line, skipping 

over intervening lines. 

Accepts value of A from keyboard. 

Accepts value of string variable A from keyboard 

The string does not have to be enclosed in quotes. 

Accepts specified variables from keyboard. 

Accepts value of A from logical file L. 

Accepts specified string from logical file L. 

Accepts specified variables from logical file L. Strings 

do not have to be enclosed in quotes. 

If condition is 'TRUE', instruction following 'THEN' 

(in this example, 'PRINT A') is executed. Otherwise, 

the next statement in sequence is executed. 

If condition is true, control is transferred to specified 

line. Otherwise, the next statement, following the IF . 

. . GOTO, is executed. 

Returns leftmost A characters from string. 

Returns length of string. 

Assign a value to a variable. 
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COMMAND/ 

STATEMENT 



EXAMPLE 



PURPOSE 



LIST 


LIST 




LIST -n 




LIST n-m 




LIST n- 


LOAD 


LOAD 




LOAD "NAME" 




LOAD "NAME", D 


MID$ 


10 ?MID$(X$,A,B) 


NEW 


NEW 


ON . . . GOTO 


10 ON A GOTO m,n,r 


ON . . . GOSUB 


10 ON A GOSUB m,n,r 


OPEN 


10 OPEN L 




20 OPEN L,D 




30 OPEN L,D,C 




40 OPEN L,D,C, "NAME" 


PEEK 


PEEK(A) 


POKE 


POKE A,B 


POS 


10 PRINT POS(0) 


PRINT 


10 PRINT A 




20 PRINT A$ 




30 PRINT A,A$ 



40 PRINT A;A$ 



READ 


50 PRINT#L,A 

60 PRINT#L,A$ 

10 READ A 

20 READ A$ 

30 READ A,A$,B,B$ 


REM 


10 REM **COMMENT** 


RESTORE 


10 RESTORE 


RETURN 


1000 RETURN 


RIGHTS 
RUN 


10 ?RIGHT$(X$,A) 

RUN 

RUNn 


SAVE 


SAVE 

SAVE "NAME" 
SAVE "NAME",D 
SAVE "NAME",D,C 



STOP 



STOP 



Lists current program. 

List current program up to line n. 

Lists lines n to m of current program. 

Lists current program from line n to end. 

Loads next encountered program from tape unit. 

Loads program NAME from tape unit. 

Loads program NAME from device D. 

Returns B characters from string, starting with the 

A th character. 

Deletes current program from memory, sets 

variables to zero. 

Transfers control to specified line (in this example m, 

n or r, depending on value of index A). 

Begins execution of subroutine which begins on line 

m, n or r, depending on the value of index A. 

Opens logical file L for read only from tape unit. 

Opens logical file L for device D. 

Opens logical file L for command C from device D. 

Opens logical file L on device D; if device D accepts 

formatted files, file NAME is positioned for 

command. 

Returns byte value from address A. 

Loads number B into address A. 

Prints next available print position of cursor on 

screen. (Dummy argument - may be string or 

numeric.) 

Prints value of A on display screen. 

Prints specified string on screen. 

Prints specified values of variables on screen, 

beginning in next available print position 

(pre-TABbed positions are in columns 0, 10, 20, 30 

etc). 

Prints specified values and strings on screen 

separated by 3 spaces if numeric, concatenated if 

strings. 

Prints specified value to logical file L. 

Prints specified string to logical file L. 

Obtains value of A from DATA statement. 

Obtains string value for A$ from DATA statement. 

Obtains specified values for strings and numeric 

variables from DATA statements. 

Inserts non-executable comments in a program for 

documentation purposes. 

Permits re-reading of DATA statements without 

re-running program. 

Subroutine exit; transfers control to the statement 

following most recent GOSUB directing transfer to 

the subroutine. 

Returns rightmost A characters from string. 

Begins execution of program at lowest line number. 

Begins execution of program at line n. (Resets 

variables.) 

Saves current program on tape unit. 

Saves current program NAME on tape unit. 

Saves current program NAME on device D. 

Saves program NAME on device D. C specifies End 

of File, or End of Tape. 

Stops program execution (see CONT). 
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COMMAND/ 

STATEMENT 



EXAMPLE 



PURPOSE 



SYS 



SYS(X) or SYSX 



SPC 

STEP 


10 SPC(N) 

10 FOR A= TO 20 STEP 2 


STR$ 
TAB 


90 NEXT A 

10 A$ = STR$(A) 

10 PRINT TAB(N);A 




20 PRINT TAB(N);A$ 


TI$ 
TI 


TI$ = "HHMMSS" 
PRINT TI 



USR 

WAIT 

VAL 
VERIFY 



USR(X) 

WAIT A,B,C 

10 A=VAL(A$) 
10 VERIFY 

20 VERIFY "NAME" 

30 VERIFY "NAME",D 



Complete control of PET is transferred to a machine 

code routine at decimal address contained in the 

argument. 

Prints N spaces or blanks. 

Step specifies size of increment to be added to index 

to increase or decrease its value towards 

the specified limit. 

Returns string representation of number. 

Prints value of A in character position N+l on 

screen. 

Prints string beginning in character position N+ 1 on 

screen. 

Set PET's internal clock to real time. 

Displays number of "jiffies" since PET was powered 

up or clock was zeroed. (A jiffy = 1/60 of a second). 

Transfers program control to a machine code 

program whose start address is stored at locations 1 

and 2. X is a parameter passed to and from the 

machine language monitor. 

Stops execution of BASIC until contents of location 

A, ANDed with B and exclusive ORed with C, is not 

equal to zero. C is optional and defaults to zero. 

Returns numeric representation of string; if string 

not numeric, returns "0". 

Verifies most recent program saved on cassette by 

reading it and comparing it with program still in 

PET's memory. 

Verifies specified program NAME saved on cassette 

by reading it and comparing it with program still in 

PET's memory. 

Verifies specified program NAME saved on device D 

by reading it and comparing it with program still in 

PET's memory. 



BASIC 4 incorporates a number of additional disk and file handling commands which are discussed in the 
relevant chapters. 
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ARITHMETIC FUNCTIONS 



FUNCTION 


EXAMPLE 


ABS 


10 C = ABS(A) 


ATN 


10 C = ATN(A) 


COS 


10 C = COS(A) 


DEFFN 


10 DEF FNA(B) 


EXP 


IOC = EXP(A) 


INT 


10 C = INT(A) 


LOG 


10 C = LOG(A) 


RND 


10 C = RND(A) 



PURPOSE 



SGN 



SIN 

SQR 

TAN 



10 C = SGN(A) 



10 C = SIN(A) 

10 C = SQR(A) 
10 C = TAN(A) 



Returns magnitude of argument without regard to 
sign. 

Returns arctangent of argument; C will be expressed 
in radians. 

Returns cosine of argument. A must be expressed in 
radians. 
= C*B t2 Allows user to define a function. Argument B is a 

dummy variable. 

Returns constant 'e' raised to power of the argument. 
In this example, e A . 

Returns largest integer less than or equal to 
argument. For example INT(-3.6) returns value of -4. 
Returns natural logarithm of argument. Argument 
must be greater than or equal to zero. 
Generates a random number between zero and one. 
If A is less than the same random number sequence 
is produced for a given A. If A equals the sequence 
of random numbers is generated from a free-running 
clock and is not repeatable. IF A is greater than 
then, from power up, the same sequence is produced. 
(N.B. BASIC 2 operates in a slightly different way). 
Returns -1 if argument is negative, returns if 
argument is zero, and returns + 1 if argument is 
positive. 

Returns sine of argument. A must be expressed in 
radians. 

Returns square root of argument. 
Returns tangent of argument. A must be expressed in 
radians. 
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ARITHMETIC, RELATIONAL AND BOOLEAN OPERATORS 



SYMBOL 



EXAMPLE 



* 

+ 



Relational 
Operators 



Boolean 
Operators 



e-g 



<> 
< 
> 
< = 

> = 

AND 
OR 
L NOT 



eg 



eg 



e-g 



e-g 



eg 



10 A= B 

10 LET A= B 

10 C=A/B 

10C=A*B 

10 C=A+B 

10 C=A-B 

10 B= Ct2.3 

A=B 

10 IF A=B THEN GOTO n 

AOB 

10 IF A<> B THEN GOSUB n 

A<B 

10IFA<BTHENC=23 

A>B 

10 IF A>B THEN G$="YES" 

A<=B 

10 IF A< =B THEN n 

A>=B 

10 IF A>=B GOSUB n 

A ANDB 

A ORB 

NOT A 



PURPOSE 



Assigns a value to a variable 

LET is optional 

Division 

Multiplication 

Addition 

Subtraction 

Raises variable to specified power. 

True if A is equal to B 

True if A is not equal to B 

True if A is less than B 

True if A is greater than B 

True if A is less than or equal to B 

True if A is greater than or equal to B 

True if A and B are both true A and B here must be 
True if either A or B is true Boolean variables, with 

True if A is not true values of either or 1 . 



N.B. The Boolean operators may also be applied to numbers or numerical variables; the process is complex and 
can properly be understood only by a detailed inspection of the binary representations of the numbers 
concerned. This is demonstrated in Chapter 13. 
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EXTENSION ROM's FOR THE PET/CBM 

A number of plug-in ROM's can be purchased, which extend the facilities of the PET in various ways. 
The following brief notes on a few of these chips may be of interest. 

1) The Programmer's Toolkit 

This chip offers a number of useful additional commands. As well as allowing a program to be traced 
through either at reduced speed or in single steps, the Toolkit allows data files or program segments 
read from cassette to be appended to a program already in the machine. Another command causes 
every line containing a specified string to be listed. Complete sections of program can be deleted, and 
the lines of a program can be automatically numbered or renumbered. The HELP command, 
following a syntax error, causes the offending line to be reprinted with the error high-lighted. 

The HELP, AUTO (number) and RENUMBER commands alone make the Toolkit well worth 
the modest purchase price. 

2) The Petmaster Superchip 

This chip can be used on its own, but since the facilities offered are essentially complementary to those 
of the Toolkit, is best used in conjunction with the latter. A number of useful facilities are offered, 
including a range of screen-handling facilities very similar to those offered in the 8000-series 
machines. The character sets may be interchanged by a key stroke, without the tedious POKE 59468, 
12 or 14 command. A RETRACE (as opposed to TRACE) facility is offered, allowing the user to 
back-track from a program error. The PET can also be stopped completely in its tracks; when this is 
done even the system clock stops counting. 

SHRINK removes all REM's and unnecessary spaces in a program, to economise on memory. A 
number of other facilities are available, including automatic key repeat (invaluable for editing) and 
single-key entry of 26 BASIC commands. This facility is particularly useful where the machine is used 
for class demonstrations, but is gratifying to have at all times. These two facilities alone are worth the 
(rather high) price. 

3) The Pic-Chip 

The Pic-Chip is designed solely for use in conjunction with graphics displays. It does not introduce any 
new graphics symbols, but allows the existing PET graphics symbols to be simply manipulated in a 
variety of ways. Since the commands used are rather specialised, being essentially an extension of PET 
BASIC, the properties of the chip are best seen by running the demonstration programs. The Pic-Chip 
is a relatively specialised device. 

4) Other add-on ROM's; shortage of ROM sockets 

A number of software packages such as Visicalc now incorporate a plug-in chip (a "dongle") as 
security against copying. While not strictly an extension ROM in the sense of those described above, 
such a chip competes with other add-on ROM's for the limited number of sockets available. Various 
means may be used to overcome this. The ROM's may be "piggy-backed" and controlled by an 
external switch or switches, or an extension board may be used. A very convenient commercially- 
produced extension board is the "ROM Pager" produced by Reprodesign Microcomputer Services. 
This allows up to eight ROM's to be used, the required chip being selected by a software command. 

5) Use of Extension ROM's with the Computhink Disk Drive 

The Computhink disk drive system also competes for some of the ROM space available. Your PET 
dealer should therefore be consulted before the purchase of any extension ROM, if this is to be used in 
conjunction with the Computhink drive. 
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Address, primary 67 

Address, secondary 68, 79 

Alternate character set 28 

Anagrams 46 

Animation 22 

Arithmetic functions Appendix B 

ASC 27 

ASCII 27 

Assembler 177 

Auxiliary control register 163 

BAM 127 

BASIC 4.0 15 

BASIC commands Appendix C 

BASIC 115 

BASIC 215 

Block allocation map see BAM 

Block read 135 

Block write 132 

Block 112 30 

Boolean logic 37, 157 

Bounce, contact 162 

Bubble sort 51 

Bus, address 149 

Bus, control 149 

Bus, data 150 

Cassette 103 
Cassette buffer 171 
CHR$ 27, 76 
CLOSE 68 
CMD73 
COLLECT 129 
Computhink 99 
Concatenation 38 
Contact bounce 162 
Cursor control 20 

Data, direction see DDR 
Data indicator 154 
Data register 755 
DDR 155 
Directory 91 
Dongle Appendix C 
DOS Support 97 

Enhanced printing 77 
Error messages 112 
Expansion port 151 

File, logical 67 



Floppy disk 91 
Format 80 
Functions Appendix B 

GET #69 
Graphics 19, 30 

Handshake 159 
Hexadecimal 172 

IEEE 67, 150 
Indexed file 112 
Indexed sort 56 
Input #69 
Insertion sort 57 
Interface 150 

Labelling 41, 42 
LEFTS 39 
Loader 173 
Logic 157 

Logical file, see 'file' 
Lower case 76 

Machine code 171 
Masking 157 
Memory expansion 151 
Memory map 150 
MID$ 39 
Music 765 

OPEN 68, 103 
Overprinting 79 

Paging 78 

PEEK 27 

Peripheral control register 752 

Pic-Chip Appendix C 

Pixel 19 

POKE 27 

PRINT #69 

Printer 73 

Program Counter 777 



Quicksort 59 

Random Access File 777, 
Relative file 777, 775 
RIGHTS 39 
ROM pager Appendix C 

Searching 45, 124 
Sequential file 777 
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GETTING MORE FROM YOUR PET/CBM 



Shell sort 58 

Shift register 163, 164 167 

Sketching (screen) 19 

Skip character 81 

Sort effort 52, 58 

Sorting 5 

Sound box 163 

SVC 21 

Stack 59 

String array 39 

String comparison 37 

Strings 37 

Strings, alphanumeric 37 

Strings, mixed 80 

Superchip 12.6, Appendix C 



System architecture 149 

Terminal Interface Monitor 175 
Toolkit Appendix C 

Universal Wedge 96 
Upper case 76 
User file 124, 129, 135 
User port 151, 153 

V AL 141 
VALIDATE 129 
Validation program 143 
Variable names 64 
VERIFY 93 
VIA chip 151, 155 



PROGRAM DISK 

A 5i inch floppy disk containing all of the main programs listed in this book can be obtained from: 

A. R. B. Associates 

445 Wilbraham Road, 

Chorlton-cum-Hardy 
Manchester M21 1US 
U.K. 

Price £19.95 inc. postage within the United Kingdom and Europe 
£22.50 outside the U.K. 
(State if 8000-series disk format required) Prices correct at September 1982. 



